Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Start an integration
Products
Global Payouts
Capital
Issuing cards
Treasury
    Overview
    How Treasury works
    Eligibility requirements
    Get Started
    Get started with API access
    Onboarding users
    Managing fraud
    Marketing and compliance guidelines
    Sample integrations
    Use Treasury to set up financial accounts and cards
    Use Treasury to move money
    Issuing and Treasury sample application
    Stripe Issuing and Treasury
    Webhooks for Stripe Issuing and Stripe Treasury
    Working with Stripe Issuing cards
    Account management
    Stripe Treasury accounts structure
    Working with connected accounts
    Working with financial accounts
    Financial account features
    Platform financial accounts
    Working with balances and transactions
    Moving money
    Payouts and top-ups from Stripe Payments
    Working with SetupIntents, PaymentMethods, and BankAccounts
    Moving money into financial accounts
    Moving money out of financial accounts
      Moving money with Treasury using OutboundTransfer objects
      Moving money with Treasury using OutboundPayment objects
      Moving money with Treasury using ReceivedDebit objects
      Moving money with Treasury using DebitReversal objects
    Money movement timelines
    Bank partners
    Fifth Third Bank overview
    Get started with Fifth Third Bank
Manage money
HomeMoney managementTreasuryMoving money out of financial accounts

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.

Copy page

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 REASONDEADLINE (EPOCH TIMESTAMP)EXAMPLE SCENARIO
null7940828047A 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_passed1629480538A 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_reversednullA ReceivedDebit that’s already been returned. It might have a non-null deadline value.
source_flow_restrictednullA ReceivedDebit that can’t be returned because its source_flow 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.

Create 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.

Command Line
cURL
curl https://api.stripe.com/v1/treasury/debit_reversals \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -H "Stripe-Account:
{{CONNECTED_ACCOUNT_ID}}
"
\ -d received_debit={{RECEIVED_DEBIT_ID}} \ -d "metadata[reason]"=Because

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.

Command Line
cURL
curl https://api.stripe.com/v1/treasury/debit_reversals/{{DEBIT_REVERSAL_ID}} \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -H "Stripe-Account:
{{CONNECTED_ACCOUNT_ID}}
"

If successful, the response returns the identified DebitReversal.

JSON (commented)
{ "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 /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.

Command Line
cURL
curl -G https://api.stripe.com/v1/treasury/debit_reversals \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -H "Stripe-Account:
{{CONNECTED_ACCOUNT_ID}}
"
\ -d financial_account=
{{FINANCIAL_ACCOUNT_ID}}
\ -d limit=3

Test DebitReversals

To test DebitReversals, you must first create a test ReceivedDebit. Afterwards, use POST /v1/treasury/debit_reversals 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.
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc