Legacy

Moving money using DebitReversal objects Legacy

Learn how you can retrieve funds taken out of a financial account from an external account holder.

Legacy integration

The v1 version of Treasury for platforms is a legacy integration that doesn’t support many of the features introduced in Treasury for platforms v2. Don’t build a new v1 integration.

Returning the funds from a ReceivedDebit creates a DebitReversal. You can get the funds back from a ReceivedDebit in only some scenarios (detailed in the following table). Whether you can return the funds of a ReceivedDebit depends on the network and source flow.

The reversal_details sub-hash on the ReceivedDebit resource can have the following combination of values, which determines whether you can return the ReceivedDebit funds.

Return deadlines

You have approximately 1 business day to return ACH debits using the API after receipt. After this time, ACH debit funds might still be returnable but funds return isn’t guaranteed. Contact support to request a return of funds if the reversal deadline has passed.

To create returns of ReceivedDebit funds produced by activity on Issuing cards, see the Issuing disputes guide.

Create a DebitReversal

Use POST /the relevant part of the product to create a DebitReversal. Specify the ID of the ReceivedDebit to reverse with the received_debit parameter in the body of the request.

Note

You can’t update DebitReversals, so you must set any optional metadata on creation.

The following request creates a DebitReversal based on the ReceivedDebit ID value on the required received_debit parameter. The request also sets an optional metadata value.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

If successful, the response returns the new DebitReversal object.

{
 "id": "{{DEBIT_REVERSAL_ID}}",
 "object": "debit_reversal",
 "amount": 1000,
 "currency": "usd",
 "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
 "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{URL_ID}}",
 "linked_flows": null,
 "livemode": false,
 "metadata": {},
 "network": "ach",
 "received_debit": "{{RECEIVED_DEBIT_ID}}",
 "resolution": null,
 "status": "processing",
 "status_transitions": {
 "completed_at": null
 },
 "transaction": "{{TRANSACTION_ID}}"
}

Retrieve a DebitReversal

Use GET /the relevant part of the product/{{the related setting}} to retrieve the DebitReversal with the associated ID.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

If successful, the response returns the identified DebitReversal.

Select a language

JSON (commented)

JSON

No results

{
 "id": "{{DEBIT_REVERSAL_ID}}",
 "object": "debit_reversal",
 "livemode": true | false,
 "created": "{{Timestamp}}",
 "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
 "amount": 1000,
 "currency": "usd",
 // the ReceivedDebit being returned
 "received_debit": "{{RECEIVED_DEBIT_ID}}",

List DebitReversals

Use GET /the relevant part of the product to retrieve a list of DebitReversals for the financial account with the ID provided in the required financial_account parameter. You can filter the list by standard list parameters, status, or by ReceivedDebit ID using the received_debit parameter.

{
 // Standard list parameters
 "limit", "starting_after", "ending_before",
 // Filter by financial account (Required)
 "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
 // Filter by `status`
 "status": "processing" | "canceled" | "completed"
 // Filter by ReceivedDebit
 "received_debit": "{{RECEIVED_DEBIT_ID}}",
}

The following request retrieves the last three DebitReversal objects for the identified financial account.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Test DebitReversals

To test DebitReversals, you must first create a test ReceivedDebit. Afterwards, use POST /the relevant part of the product and specify the test ReceivedDebit ID in the received_debit parameter to create a test DebitReversal.

DebitReversal webhooks

Stripe emits the following DebitReversal events to your webhook endpoint:

• treasury. debit _ reversal. created on DebitReversal creation.
• treasury. debit _ reversal. completed when the DebitReversal completes.