---
title: "Get history of payout reversals"
method: GET
path: "/payout/{user_token}/{payout_token}/reversal"
tags: ["Payout Reversal"]
---

# Get history of payout reversals

`GET /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: <https://skmtc.dev/masspay/apis/masspay-api/docs/payout/:user_token/:payout_token/reversal/get.ts> (a function with typed inputs; its response is checked against the schema)

This **GET** endpoint is used to retrieve the payout reversal history for a specific user and payout transaction.
<br> You can use this endpoint to view all reversal transactions applied to a particular payout, including each `payout_reversal_token`, the reversed amount, and status.
<br> To use this endpoint, you need to provide both the `user_token` and the original `payout_token` in the URL Path.
<br> The response will include a JSON object containing an array of reversal transactions associated with the specified payout, with each entry including details such as the reversal token, amount, currency, status, and the date and time of the reversal.

## Path parameters

- `user_token` string, required
- `payout_token` string, required

## Headers

- `Idempotency-Key` string

## 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_<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_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/get.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)