Create a transfer reversal via POST /v1/transfers/{transfer_id}/reversals; specify amount for a partial reversal or omit to reverse the full transfer
Check the connected account's Stripe balance before reversing — if the connected account has insufficient funds, the reversal will fail or create a negative balance depending on the platform's loss liability setting
Retrieve the reversal via GET /v1/transfers/{transfer_id}/reversals/{reversal_id} to confirm its status and the resulting balance impact on both the platform and connected account
Set refund_application_fee=true on a charge refund if you also want to reclaim the application fee when reversing a transfer associated with a refund
Listen to transfer.reversed webhook events to trigger downstream accounting entries and notify connected accounts of the reversal
For destination charges, passing reverse_transfer=true on the charge refund endpoint automatically creates the transfer reversal — this is simpler than manually reversing the transfer if you control both the refund and transfer
Known gotchas
Transfer reversals debit the connected account's Stripe balance; if the balance is insufficient and the platform has controller.losses.payments=application, the platform may absorb the resulting negative balance — monitor connected account balances proactively
You cannot reverse a transfer that has already been paid out to the connected account's bank — once funds leave Stripe, recovery requires the connected account to initiate a new transfer back to the platform, which is outside Stripe's API control
Partial reversals reduce the transfer amount but the original transfer object is not deleted; ensure your reconciliation logic sums original transfer amounts minus all associated reversals to compute net disbursements
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?