Moving money with Treasury using DebitReversal objects
Learn how you can retrieve funds taken out of a Treasury financial account from an external account holder.
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_
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_ | 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_ | null | A ReceivedDebit that’s already been returned. It might have a non-null deadline value. |
source_ | null | A ReceivedDebit that can’t be returned because its source_ isn’t reversible. |
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.
Creating a DebitReversal
Use POST /v1/treasury/debit_
to create a DebitReversal
. Specify the ID of the ReceivedDebit
to reverse with the received_
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_
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_
to retrieve the DebitReversal
with the associated ID.
If successful, the response returns the identified DebitReversal
.
List DebitReversals
Use GET /v1/treasury/debit_
to retrieve a list of DebitReversals
for the financial account with the ID provided in the required financial_
parameter. You can filter the list by standard list parameters, status
, or by ReceivedDebit
ID using the received_
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_
and specify the test mode ReceivedDebit
ID in the received_
parameter to create a test mode DebitReversal
.
DebitReversal webhooks
Stripe emits the following DebitReversal
events to your webhook endpoint:
treasury.
ondebit_ reversal. created DebitReversal
creation.treasury.
when thedebit_ reversal. completed DebitReversal
completes.