--- title: "Initiate a payout reversal" method: POST path: "/payout/{user_token}/{payout_token}/reversal" tags: ["Payout Reversal"] --- # Initiate a payout reversal `POST /payout/{user_token}/{payout_token}/reversal` ## Request - Base URL: `https://api.masspay.io/v1.0.0` - URL: `https://api.masspay.io/v1.0.0/payout/{user_token}/{payout_token}/reversal` - Auth: one of: - API key in header `Authorization` - API key in header `x-api-key` - TypeScript: (a function with typed inputs; its response is checked against the schema) This **POST** endpoint is used to initiate a reversal of a previously completed payout transaction.
You must specify the `user_token` and original payout (`payout_token`) in the URL path to identify which transaction should be reversed.
In the request body, you may optionally provide an `amount` to perform a partial reversal. If no amount is specified, the entire payout amount will be reversed.
Reversals can be performed multiple times until the full payout has been reversed.
Once the payout has been fully reversed, additional reversal attempts will be rejected. Attempting to reverse more than the remaining available amount will also result in an error.
The response will include the details of the reversal transaction, including the amount reversed, the remaining reversible balance (if any), and the status of the original payout. ## Path parameters - `user_token` string, required - `payout_token` string, required ## Headers - `Idempotency-Key` string ## Request body - PayoutReversalReq - `amount` number: A positive number representing the amount to reverse from the original payout. You may reverse the full amount or a partial amount, up to the remaining unreversed balance of the payout. If omitted, the full available amount will be reversed. Partial reversals are supported. The value should be specified in the `destination_currency` of the original payout. - `metadata` object: Optional JSON object with attributes that are attached to the payout reversal transaction - `client_transfer_id` string: A client defined transfer identifier. This is the unique ID assigned to the transfer on your system. Max 50 characters. A value another payout of yours already carries is rejected with `400 Bad request` and `Duplicate client id. Existing payout token: payout_` in `error.details`. By default a value becomes reusable once the earlier payout is `ERROR` or `EXPIRED` (or is a `PENDING` quote past its expiration); any other status, including `CANCELLED`, keeps it reserved. Accounts configured for strict uniqueness never allow reuse, whatever the earlier payout's status. - `statement_description` string: Optional descriptive line item that appears on the payout reversal statement, providing details about the transaction. This field is intended to help identify the purpose or source of each payout by displaying a brief summary or itemized description. Commonly includes information such as reversal reason. Note: Not all countries and banks support displaying this field. - `notify_user` boolean: Should we notify the user via email and SMS that a payout reversal was initiated aginst their account ## Response `200` successful operation - PayoutReversalResp - `payout_reversal_token` string, required: Payout Reversal Token - `source_amount` number, required: The amount that was reversed in this transaction. This can be a full or partial reversal of the original payout, depending on the requested reversal amount. The value is expressed in the same currency as the original payout. - `source_currency_code` string, required: Currency code for the amount that will be loaded onto the `source_token` - `exchange_rate` number, required: Exchange rate between the source and destination amounts - `destination_amount` number, required: The amount that will be debited from the `attr_set_token` - `destination_currency_code` string, required: The currency in which the funds were received and will be debited from the `attr_set_token` associated with the original `payout_token` - `status` 'PENDING' | 'EXPIRED' | 'PROCESSING' | 'COMPLETED' | 'CANCELLED' | 'SCHEDULED' | 'READY_FOR_PICKUP' | 'HOLD' | 'ERROR', required: Status of Payout Reversal - `status_reason` string: When available, contains the reason code for the reversal status - `payout_token` string, required: Token of the Payout the reversal is applied to - `metadata` object, required: Optional JSON object with attributes that are attached to the payout reversal transaction - `fee` number, required: Fee associated with the payout reversal - `client_transfer_id` string: A client defined transfer identifier. This is the unique ID assigned to the transfer on your system. Max 50 characters. A value another payout of yours already carries is rejected with `400 Bad request` and `Duplicate client id. Existing payout token: payout_` in `error.details`. By default a value becomes reusable once the earlier payout is `ERROR` or `EXPIRED` (or is a `PENDING` quote past its expiration); any other status, including `CANCELLED`, keeps it reserved. Accounts configured for strict uniqueness never allow reuse, whatever the earlier payout's status. - `original_destination_amount` number, required: The original `destination amount` that was deposited in the payout - `total_reversed_amount` number, required: The total amount that was reversed against the original payout so far - `created` string, date-time, required: Datetime of when the reversal was created. Provided in UTC - `completed` string, date-time: Datetime of when the payout reversal was completed and credited to the `source_token` of the original payout. Provided in UTC ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: You do not have necessary permissions for the resource - `404`: Not Found - `405`: Invalid input - `500`: Internal Server Error - `504`: Gateway Timeout ## Changes - **2026-11-03** `f9fa41b7c45c`: 1 info - endpoint added [Operation history](https://skmtc.dev/masspay/apis/masspay-api/changes/payout/:user_token/:payout_token/reversal/post.md) --- [API](https://skmtc.dev/masspay/apis/masspay-api.md) - [All operations](https://skmtc.dev/masspay/apis/masspay-api/llms.txt) - [OpenAPI document](https://skmtc.dev/masspay/apis/masspay-api/revisions/f9fa41b7c45c?raw)