Retrieve the Transfer ID associated with the original charge or payment; it appears in the transfer_data on the charge or as a separate Transfer object.
Create a Transfer Reversal via POST /v1/transfers/{transfer_id}/reversals, supplying amount (partial reversal) or omitting it to reverse the full transfer.
The reversal moves funds from the connected account's Stripe balance back to the platform's balance — confirm the connected account has sufficient balance before reversing.
Check the reversal object's status after creation; it should reflect the reversal amount against the original transfer.
If the connected account's balance is insufficient to cover the reversal, Stripe will fail the reversal — you must handle negative balance liability according to your Connect configuration.
Reconcile via balance_transaction objects: the reversal generates a 'transfer_reversal' type transaction on the platform account.
Known gotchas
You cannot reverse a transfer that has already been paid out to the connected account's bank account; arrange reversals before payout or recover funds out-of-band.
Partial reversals are allowed but cannot exceed the original transfer amount minus any previous reversals.
Reversing a transfer does not automatically refund the customer — refund the original PaymentIntent separately if needed.
Give your agent this knowledge — and 15,800+ more routes
One MCP install gives any agent live access to the full route map across 5,800+ 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?