MAmasspay
Payout Reversal

Initiate a payout reversal

Changed on

This POST endpoint is used to initiate a reversal of a previously completed payout transaction. <br> You must specify the user_token and original payout (payout_token) in the URL path to identify which transaction should be reversed. <br> 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. <br> Reversals can be performed multiple times until the full payout has been reversed. <br> 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. <br> 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.

post/payout/{user_token}/{payout_token}/reversal

Request

Path parameters

user_tokenstring required

Token representing the user to pay out

payout_tokenstring required

Token representing the trsanaction. Retrieved from /payout/{user_token}

Headers

Idempotency-Keystring

Unique key to prevent duplicate processing

Request body

amountnumber

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.

metadataobject

Optional JSON object with attributes that are attached to the payout reversal transaction

client_transfer_idstring

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_<uuid> 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_descriptionstring

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_userboolean

Should we notify the user via email and SMS that a payout reversal was initiated aginst their account

Example request

{
  "amount": 100.5
}

Response

successful operation

payout_reversal_tokenstring required

Payout Reversal Token

source_amountnumber 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_codestring required

Currency code for the amount that will be loaded onto the source_token

exchange_ratenumber required

Exchange rate between the source and destination amounts

destination_amountnumber required

The amount that will be debited from the attr_set_token

destination_currency_codestring 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_reasonstring

When available, contains the reason code for the reversal status

payout_tokenstring required

Token of the Payout the reversal is applied to

metadataobject required

Optional JSON object with attributes that are attached to the payout reversal transaction

feenumber required

Fee associated with the payout reversal

client_transfer_idstring

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_<uuid> 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_amountnumber required

The original destination amount that was deposited in the payout

total_reversed_amountnumber required

The total amount that was reversed against the original payout so far

createdstring date-time required

Datetime of when the reversal was created. Provided in UTC

completedstring date-time

Datetime of when the payout reversal was completed and credited to the source_token of the original payout. Provided in UTC

Example response

{
  "status_reason": "R01 - Insufficient Funds",
  "original_destination_amount": 1000.34,
  "total_reversed_amount": 10.2
}

Changes