Moving money with Treasury using DebitReversal objects
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.
RESTRICTED REASON | DEADLINE (EPOCH TIMESTAMP) | EXAMPLE SCENARIO |
---|---|---|
null | 7940828047 | A ReceivedDebit that you can return funds from, but only until the timestamp in deadline . ACH ReceivedDebits have a deadline that determines how long you have to return them. |
deadline_passed | 1629480538 | A ReceivedDebit whose funds were returnable before the timestamp in deadline , but is no longer returnable using the API because the deadline has passed. ACH ReceivedDebits have a limited time of when they’re returnable using the API after they’re created. |
already_reversed | null | A ReceivedDebit that’s already been returned. It might have a non-null deadline value. |
source_flow_restricted | null | A ReceivedDebit that can’t be returned because its source_flow isn’t reversible. |
Return deadlines
You have 36 hours 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 36 hours have passed.
To create returns of ReceivedDebit
funds produced by activity on Issuing
cards, see the Issuing disputes guide.
Creating a DebitReversal
Use POST /v1/treasury/debit_reversals
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.
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 /v1/treasury/debit_reversals/{{DEBIT_REVERSAL_ID}}
to retrieve the DebitReversal
with the associated ID.
If successful, the response returns the identified DebitReversal
.
List DebitReversals
Use GET /v1/treasury/debit_reversals
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.
Testing DebitReversals
To test DebitReversals
, you must first create a test mode ReceivedDebit. Afterwards, use POST /v1/treasury/debit_reversals
and specify the test mode ReceivedDebit
ID in the received_debit
parameter to create a test mode DebitReversal
.
DebitReversal webhooks
Stripe emits the following DebitReversal
events to your webhook endpoint:
treasury.debit_reversal.created
onDebitReversal
creation.treasury.debit_reversal.completed
when theDebitReversal
completes.