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

# Get status of a payout by payout token

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

This **GET** endpoint is used to retrieve the status of a payout transaction for a user with the specified token and payout token. <br> You can use this endpoint to check the status of a specific payout transaction, including whether the payout has been successfully processed or if there was an error. <br> To use this endpoint, you need to provide the `user_token` and `payout_token` in the URL Path. <br> The response will include a JSON object containing details about the payout transaction.

## Query parameters

- `force_status_update` boolean
- `include_payer_logo` boolean

## Headers

- `Idempotency-Key` string

## Response `200`

OK

- PayoutTxnResp
  - `payout_token` string, uuid, required — Token that represents the transaction that was just created. Need to be used to commit the transaction in `/payout/{user_token}/{payout_token}`. Value would be NSF if there are not enough funds in the `source_token`. Value would be `DUPLICATE` if there is a duplicate `client_transfer_id`.
  - `client_transfer_id` string, required — A client defined transfer identifier. This is the unique ID assigned to the transfer on your system. Max 50 characters.
  - `source_currency_code` string, required — The currency originating balance is stored in. Using [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. In most cases this value will be USD, and therefore the defaut value if none is provided
  - `destination_currency_code` string, required — The currency the funds will be deposited into. Using [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format
  - `source_token` string, uuid, required — Token that represents the funding source i.e. your bank account, user's wallet. 36 characters long
  - `destination_token` string, uuid, required — Token that represents the payout destination i.e. MassPay->Brazil->Bank Deposit->Itau. To be retrieved from the #pricing callback. If not provided, the last destination that was used for this user will be used. 36 characters long
  - `destination_amount` number, float, required — The amount to be sent for payout in source currency. i.e USD. Must be provided if source_amount is empty
  - `source_amount` number, float, required — The amount to be received by the payout in source currency. i.e USD. Must be provided if destination_amount is empty
  - `attr_set_token` string, uuid, required — Token that represents set of attributes that associated with destination_token. For example, bank account, mobile account, wallet id, etc. If not provided, uses the last one used. 36 characters long
  - `exchange_rate` number, float, required — The exchange rate to convert source_amount to destination_amount
  - `fee` number, float, required — Fee to be charged for the transaction
  - `expiration` string, YYYY-MMDDThh:mm:ss, required — The time and date at which the transaction will expire. The transaction has to be finalized before this time. Transactions are valid for 2 minutes from creation time. If expired, a new transaction has to be created.
  - `pickup_code` string, required — Confirmation/transaction code issued by the sending network or payout partner. For cash pickups, this is the code used to release cash to the recipient. For non-cash rails, it serves as a confirmation reference that you or banking partners can use to look up the transaction. Not the same as `trace_code`.
  - `trace_code` string — Receiving-institution tracking identifier for the underlying transfer. Used by the **receiving** rail/operator to locate the transaction in its ledger (e.g., blockchain, ACH operator, bank). For crypto, this is the blockchain transaction hash. For ACH, this is the 15-digit ACH Trace Number. This value is distinct from `pickup_code`.<br> <br> Trace numbers are **not supported for all transactions** and will only be set when the rail supports them. In some cases, the value may be updated up to **14 days after the transaction** as the receiving institution posts or confirms it.
  - `status` 'PENDING' | 'EXPIRED' | 'PROCESSING' | 'COMPLETED' | 'CANCELLED' | 'SCHEDULED' | 'READY_FOR_PICKUP' | 'HOLD' | 'ERROR', required — The status of the transaction
  - `payer_logo` string, byte — base64 representation of the payer logo
  - `payer_name` string, required — Name of payer
  - `delivery_type` 'CASH_PICKUP' | 'BANK_DEPOSIT' | 'HOME_DELIVERY' | 'MOBILE_WALLET' | 'MASSPAY_CARD' | 'PAPER_CHECK' | 'BILL' | 'CRYPTOCURRENCY', required — The type of delivery
  - `country_code` string, required — Country code [ISO_3166](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)
  - `metadata` object — Optional JSON object with attributes that can later be searched to locate this payout. Do not include PII as this object is not encrypted.
  - `estimated_availability` string, date-time, required — Estimated availability of funds. When funds would be available to pickup/deposited
  - `status_reason` string — Optional. Contains the reason for the status change. Most commonly used for CANCELLED status with the reason for cancellation
  - `attrs` object — The relevant attributes that were used to fulfill this payout
  - `reversible_amount` number, float, required — The total amount that can be reversed against this payout. If 0, it means that either reversals are not available for this payout `destination_token` or the full amount of the original payout was already reversed in the `destination_currency` of the original payout.

## Other responses

- `400` — Bad request.
- `401` — Unauthorized.
- `403` — Forbidden.
- `404` — Not found.
- `405` — Method Not Allowed.
- `500` — Internal server error.
- `504` — Gateway Time-out.

---

[API](https://skmtc.net/masspay/apis/masspay-api.md) · [All operations](https://skmtc.net/masspay/apis/masspay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/masspay/masspay-api/revisions/c03b61a6a551/schema)