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

# Get status of a payout reversal

`GET /payout/{user_token}/{payout_token}/reversal/{payout_reversal_token}`

## Request

- Base URL: `https://api.masspay.io/v1.0.0`
- URL: `https://api.masspay.io/v1.0.0/payout/{user_token}/{payout_token}/reversal/{payout_reversal_token}`
- 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/:payout_reversal_token/get.ts> (a function with typed inputs; its response is checked against the schema)

This **GET** endpoint is used to retrieve the status of a payout reversal transaction for a user with the specified token and payout reversal token.
<br> You can use this endpoint to check whether a reversal has been successfully processed, partially applied, or if it encountered an error.
<br> To use this endpoint, you need to provide the `user_token`, original `payout_token` and `payout_reversal_token` in the URL Path.
<br> The response will include a JSON object containing details about the reversal transaction, including its status and any remaining reversible amount.

## 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
  - added the optional property `status_reason` to the response with the `200` status

[Operation history](https://skmtc.dev/masspay/apis/masspay-api/changes/payout/:user_token/:payout_token/reversal/:payout_reversal_token/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)