Payout

Initiate a payout transaction

Changed on Nov 3, 2026

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.

post/payout/{user_token}

Request

Base URL
https://api.masspay.io/v1.0.0
Auth
- API key in header Authorization
- or API key in header x-api-key
TypeScript
https://skmtc.dev/masspay/apis/masspay-api/docs/payout/:user_token/post.ts
A function with typed inputs. Its response is checked against the schema.

Path parameters

user_tokenstring required

Example:usr_5b54fd79-2aa8-4965-85ed-0b3ad3739752

Token representing the user to pay out. Accepted either as a bare UUID or prefixed with usr_; both forms reference the same user. 36 characters long, or 40 with the usr_ prefix.

Query parameters

limitnumber

Limit amount for transaction amount + fee. If fee + amount are higher than the limit, the output will automatically adjust to maximize the possible amount sent. Amount is specified in source_currency.

dry_runboolean

When true, performs all validation checks without initiating the payout.

Headers

Idempotency-Keystring

Unique key to prevent duplicate processing

Request body

client_transfer_idstring

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.

source_currency_codestring

The currency originating balance is stored in. Fiat currencies use ISO 4217 codes (3 characters); cryptocurrency ticker symbols (e.g. USDT) may be up to 5 characters. In most cases this value will be USD, and therefore the default value if none is provided

destination_currency_codestring required

The currency the funds will be deposited into. Fiat currencies use ISO 4217 codes (3 characters); cryptocurrency ticker symbols (e.g. USDT) may be up to 5 characters

source_tokenstring required

Token that represents the funding source for the payout, i.e. a bank account or wallet. Accepted either as a bare UUID or prefixed with the source type (e.g. clnt_wlt_ for a client wallet); both forms reference the same funding source. 36 characters long, or up to 45 with a prefix.

destination_tokenstring

Optional. Token that represents the payout destination, i.e. MassPay->Brazil->Bank Deposit->Itau. To be retrieved from the #pricing callback. Accepted either as a bare UUID or prefixed with dest_; both forms reference the same destination. If not provided, the last destination that was used for this user will be used. 36 characters long, or 41 with the dest_ prefix.

destination_amountnumber float

The amount to be sent for payout in destination currency. i.e USD. Must be provided if source_amount is empty

source_amountnumber 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_tokenstring

Optional. Token that represents the set of attributes associated with the destination_token, for example a bank account, mobile account, or wallet id. Accepted either as a bare UUID or prefixed with attr_set_; both forms reference the same attribute set. If not provided, the last attr_set_token used is applied. 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. 36 characters long, or 45 with the attr_set_ prefix.

metadataobject

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_userboolean

Should we notify the user via email/sms about status updates for this payout?

auto_commitboolean

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_descriptionstring

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.

sender_user_tokenstring

Optional. Token that represents the user who is the sender (originator) of this payout. Accepted either as a bare UUID or prefixed with usr_; both forms reference the same user. Provide this field only when you are initiating the transaction on behalf of that sender, i.e. the transaction is not originated with you (the client) as the sender. When omitted, the client is considered the sender of record. The token must reference an existing user. Sender details are used for compliance, screening, and reporting purposes, so this value must accurately reflect the true originator of the funds. 36 characters long, or 40 with the usr_ prefix.

Example request

{
  "client_transfer_id": "aEjn345",
  "source_currency_code": "USD",
  "destination_currency_code": "MXN",
  "source_token": "clnt_wlt_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "destination_token": "dest_d2138fd0-00be-45a8-985f-4f5bde500962",
  "destination_amount": 100.5,
  "source_amount": 100.5,
  "attr_set_token": "attr_set_b1a867c1-6e36-4525-b6d5-a20bac80e3b0",
  "metadata": {
    "group_id": 541
  },
  "statement_description": "Merchant 4561",
  "sender_user_token": "usr_7f8e9d0c-1b2a-4c3d-9e5f-6a7b8c9d0e1f",
  "value_added_services": {
    "account_validation": {
      "validation": "SKIP"
    }
  }
}

Response

Successfully created.

Example response

{
  "payout_token": "payout_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "client_transfer_id": "aEjn345",
  "source_currency_code": "USD",
  "destination_currency_code": "MXN",
  "source_token": "clnt_wlt_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "destination_token": "dest_d2138fd0-00be-45a8-985f-4f5bde500962",
  "destination_amount": 100.5,
  "source_amount": 100.5,
  "attr_set_token": "attr_set_b1a867c1-6e36-4525-b6d5-a20bac80e3b0",
  "exchange_rate": 18.55,
  "fee": 2.99,
  "expiration": "2026-08-22T17:40:46.881Z",
  "pickup_code": "54238173",
  "trace_code": "021214893903107",
  "payer_logo": "U3dhZ2dlciByb2Nrcw==",
  "payer_name": "Elektra",
  "country_code": "MEX",
  "metadata": {
    "group_id": 541
  },
  "estimated_availability": "2020-07-21T17:32:28Z",
  "sender_user_token": "usr_7f8e9d0c-1b2a-4c3d-9e5f-6a7b8c9d0e1f",
  "reversible_amount": 100.5
}

Changes

Nov 3, 2026f9fa41b7c45c Revision changes
- breaking
  for the path request parameter user_token, the minLength was increased from 0 to 36
- breaking
  added the pattern ^(usr_)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ to the path request parameter user_token
- breaking
  the request property's minLength was increased from 0 to 36
- breaking
  the request property's minLength was increased from 0 to 3
- breaking
  the request property's minLength was increased from 0 to 36
- breaking
  the request property's minLength was increased from 0 to 3
- breaking
  the request property's minLength was increased from 0 to 36
- breaking
  added the pattern ^([a-z]+(_[a-z]+)*_)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ to the request property
- breaking
  added the pattern ^(attr_set_)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ to the request property
- breaking
  added the pattern ^(dest_)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ to the request property
- breaking
  added the pattern ^[A-Z]{3,5}$ to the request property
- breaking
  added the pattern ^[A-Z]{3,5}$ to the request property
- breaking
  the //// response's property format changed from uuid to no format for status
- breaking
  the //// response's property format changed from uuid to no format for status
- breaking
  the //// response's property format changed from YYYY-MMDDThh:mm:ss to date-time for status
- breaking
  the //// response's property format changed from uuid to no format for status
- breaking
  the //// response's property format changed from uuid to no format for status
- warning
  for the path request parameter user_token, the maxLength was set to 40
- warning
  for the query request parameter limit, the min was set to 0.00
- warning
  the request property's maxLength was set to 45
- warning
  the request property's maxLength was set to 50
- warning
  the request property's maxLength was set to 5
- warning
  the request property's maxLength was set to 41
- warning
  the request property's maxLength was set to 5
- warning
  the request property's maxLength was set to 45
- info
  added the new optional request property
- info
  removed the pattern ^[\d.]+$ from the query request parameter limit
- info
  the request property became optional
- info
  the request property format was generalized from uuid to no format
- info
  the request property format was generalized from uuid to no format
- info
  the request property format was generalized from uuid to no format
- info
  added the optional property //// to the response with the status
- info
  the //// response's property pattern ^(attr_set_)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ was added for the status
- info
  the //// response's property pattern ^[A-Z]{3}$ was added for the status
- info
  the //// response's property pattern ^[A-Z]{3,5}$ was added for the status
- info
  the //// response's property pattern ^(dest_)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ was added for the status
- info
  the //// response's property pattern ^(payout_)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ was added for the status
- info
  the //// response's property pattern ^[A-Z]{3,5}$ was added for the status
- info
  the //// response's property pattern ^([a-z]+(_[a-z]+)*_)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ was added for the status

Operation history