---
title: "Get history of payouts by user token"
method: GET
path: "/payout/{user_token}"
tags: ["Payout"]
---

# Get history of payouts by user token

`GET /payout/{user_token}`

This **GET** endpoint is used to retrieve the payout history for a user with the specified token. <br> You can use this endpoint to view all payouts made to a user, including the `payout_token`, `destinantion_token` and `destination_amount`. <br> To use this endpoint, you need to provide the user token of the recipient in the URL Path. <br> The response will include a JSON object containing an array of payout transactions for the specified user, with each transaction including details such as the transaction ID, payout amount, currency, payout status, and date and time of the payout.

## Path parameters

- `user_token` string, required

## Query parameters

- `include_payer_logos` boolean

## Headers

- `Idempotency-Key` string

## Response `200`

successful operation

- 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.
- `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)