Reversals
A Reversal object represents a settled payout that you've undone. When you reverse a payout, Payonify returns the money you sent. Reversals work for standard payouts and Relay transfers, and a payout can be reversed once, for the full amount.
List reversals
Returns the reversals you've created, most recent first. Supports cursor pagination
and filtering by status and currency.
query Parameters
firstReturns the first n reversals. Use with after for forward pagination.
afterA cursor to fetch results after. Use with first.
lastReturns the last n reversals. Use with before for backward pagination.
beforeA cursor to fetch results before. Use with last.
statusFilter by reversal status.
currencyFilter by currency (ISO code, e.g. usd).
start_dateOnly return reversals created on or after this date (YYYY-MM-DD).
end_dateOnly return reversals created on or before this date (YYYY-MM-DD).
List reversals › Responses
A list of transfer reversals
objectType of the returned object.
Array of reversal objects.
Pagination metadata
Create a reversal
Creates a reversal for a settled payout or Relay transfer, returning the money you sent. It can be reversed once, and always for the full amount.
The reversal is processed in the background, so you get a response right away with a
processing status and a webhook once it completes as succeeded or failed.
Reversal status
A reversal can have one of the following statuses:
processing: The reversal has been created and is being processed.succeeded: The money was returned to you.failed: The reversal did not go through.
Create a reversal › Request Body
payoutThe identifier of the payout to reverse (po_...). Use this for standard payouts.
transferThe identifier of the Relay transfer to reverse (tr_...). Use this for Relay
transfers.
reasonAn optional note for your own record-keeping on why it was reversed.
Create a reversal › Responses
Reversal created successfully
idUnique identifier for the reversal object. Reversal IDs have the prefix rev_.
objectA string representing the type of the object. Always "reversal".
The amount reversed. Always the full amount originally sent.
payoutThe ID of the payout that was reversed. Present when a payout was reversed.
transferThe ID of the Relay transfer that was reversed. Present when a Relay transfer was reversed.
statusThe status of the reversal.
Possible values:
processing: The reversal has been accepted and is being processed.succeeded: The money was returned to the sender.failed: The reversal did not go through; nothing changed.
reasonThe note you attached when creating the reversal, if any.
Details of the reversed payout or transfer. The mobile-money reference (the
reversal's own gateway reference) fills in once the reversal completes.
livemodeHas the value true if the object exists in live mode or false if in test mode.
createdTime at which the object was created. Measured in seconds since the Unix epoch.
failure_codeError code for a failed reversal. null unless the reversal failed.
failure_messageA human-readable message describing why the reversal failed. null unless the
reversal failed.
Retrieve a reversal
Fetches a single reversal by its ID. Use it to check the status of a reversal, its gateway reference once it completes, and the failure reason if it didn't go through.
path Parameters
idUnique identifier for the reversal (e.g. rev_...).
Retrieve a reversal › Responses
Reversal details retrieved successfully
idUnique identifier for the reversal object. Reversal IDs have the prefix rev_.
objectA string representing the type of the object. Always "reversal".
The amount reversed. Always the full amount originally sent.
payoutThe ID of the payout that was reversed. Present when a payout was reversed.
transferThe ID of the Relay transfer that was reversed. Present when a Relay transfer was reversed.
statusThe status of the reversal.
Possible values:
processing: The reversal has been accepted and is being processed.succeeded: The money was returned to the sender.failed: The reversal did not go through; nothing changed.
reasonThe note you attached when creating the reversal, if any.
Details of the reversed payout or transfer. The mobile-money reference (the
reversal's own gateway reference) fills in once the reversal completes.
livemodeHas the value true if the object exists in live mode or false if in test mode.
createdTime at which the object was created. Measured in seconds since the Unix epoch.
failure_codeError code for a failed reversal. null unless the reversal failed.
failure_messageA human-readable message describing why the reversal failed. null unless the
reversal failed.