Create a transfer reversal
Move the funds back the way they came. Partial reversals are allowed, repeatedly, up to the transfer's unreversed remainder. Once a transfer is fully reversed it cannot be reversed again.
Only paid transfers can be reversed. Before that the money has not arrived, so cancel the
transfer instead. A failed transfer has nothing to reverse: the funds were already
returned.
Authorization
X-API-Key X-Publishable-Key Your Bolt API key, from Developer > API in the Bolt Merchant Dashboard. Server-side only.
Sandbox keys work only against api-sandbox.boltapp.com. Using a sandbox key against
production, or the reverse, returns 401.
In: header
The publicly shareable identifier for your merchant division. Your authenticated account is always one side of a transfer, and seller IDs are resolved against it.
In: header
Path Parameters
The ID of the transfer to operate on.
Header Parameters
Bolt's standard replay protection for POST and PATCH requests. Use a UUID, up to 255
characters. A key can only be replayed on an identical request, and a replayed response
carries Idempotent-Replayed: true. Concurrent requests sharing a key return 409. Keys
expire after 24 hours.
On Create transfer this is secondary to reference, whose protection does not expire.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v3/transfers/trf_9f8e7d6c5b/reversals" \ -H "Idempotency-Key: 8f14e45f-ea8f-4b3c-9b1a-0d1c2e3f4a5b" \ -H "Content-Type: application/json" \ -d '{ "reference": "reversal-full-8840", "description": "Payout issued in error" }'{ "id": "trr_4a3b2c1d0e", "created_at": "2026-10-20T11:02:44Z", "transfer_id": "trf_9f8e7d6c5b", "status": "pending", "amount": { "units": 1500, "currency": "USD" }, "reference": "reversal-return-8831", "description": "Partial return, 1 of 3 items", "payout_reference": null, "metadata": {}}