---
title: "Initiate a payout transaction"
method: POST
path: "/payout/{user_token}"
tags: ["Payout"]
---

# Initiate a payout transaction

`POST /payout/{user_token}`

This **POST** endpoint is used to initiate a payout transaction from your account to a user with a specified token.
<br> You can use this endpoint to pay out funds to your users, such as payments for services rendered or rewards for completing tasks. To use this endpoint, you need to provide the user token of the recipient in the URL Path.
<br> The request body should include the funding source (`source_token`), payout destination (`destination_token`) and specify in which currency the payout should be made (`destination_currency_code`).
<br> As a response API will return all details about your payout transaction.

## Path parameters

- `user_token` string, required

## Query parameters

- `limit` number
- `dry_run` boolean

## Headers

- `Idempotency-Key` string

## Request body

- PayoutTxn
  - `client_transfer_id` string — A client defined transfer identifier. This is the unique ID assigned to the transfer on your system. Max 50 characters.
  - `source_currency_code` string — 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. bank account, 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 — The amount to be sent for payout in destination currency. i.e USD. Must be provided if source_amount is empty
  - `source_amount` number, float — 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 — 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 `attr_set_token` used. 36 characters long. If this is the first payout that is initiated for the `user_token` and `destination_token` combination and an `attr_set_token` is not provided, the latest attributes that were stored would be used.
  - `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. There are two special attributes that can be provided in the metadata field: `batch_identifier` and `batch_name`. Either of those values, would group transactions in the ledger under the same description.
  - `notify_user` boolean — Should we notify the user via email/sms about status updates for this payout?
  - `auto_commit` boolean — Auto commit would commit the payout without requiring the API call to the commit payout endpoint. This option is only available when the `source_currency` and the `destination_currency` are the same. Whenever an exchange rate is applied to a transaction, a separate commit call is required.
  - `statement_description` string — Optional descriptive line item that appears on the payout 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 transaction type, merchant name, or payout reason. Note: Not all countries and banks support displaying this field.
  - `value_added_services` ValueAddedServicesPayouts — Optional per-transaction overrides for payout value added services. Omitted properties default to the account's configuration.
    - `account_validation` AccountValidationVAS — Controls whether account validation runs for this transaction.
      - `validation` 'RUN' | 'SKIP' | 'ACCOUNT_DEFAULT' — `RUN` always runs account validation for this transaction, even if the account configuration has it disabled. `SKIP` never runs account validation for this transaction, even if the account configuration has it enabled. `ACCOUNT_DEFAULT` (the default when omitted) defers to the account's configuration.

## Response `201`

Successfully created.

- union
  - 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.
  - PayoutTxnCommitResp
    - `payout_token` string, uuid, required — Token that represents the transaction that was just created.
    - `status` 'success' | 'failure' | 'addtl_attr_req' | 'ex_rate_expired' | 'nsf', required — Status that indicates whether the transaction was successfully processed. If `success`, everything was processed correctly. `failure` indicates a generic error. `addtl_attr_req` indicates that in order to process this transaction, additional attributes are required to be updated for this customer. `ex_rate_expired` indicates that the transaction exchange rate has expired and a new transaction has to be created.
    - `pickup_code` string — Code/pin that is required when collecting the money. Should be provided to the recipient to present to payout location.
    - `errors` string — Description of errors preventing transfer from being injected.

## 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)