Initiate a payout transaction

post

https://{environment}.masspay.io/{VERSION}/payout/{user_token}

This POST endpoint is used to initiate a payout transaction from your account to a user with a specified token.
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.
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).
As a response API will return all details about your payout transaction.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

user_token

string

required

length between 36 and 40

^(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}$

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 Params

limit

number

≥ 0

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_run

boolean

Defaults to false

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

Body Params

Payout parameters for a quote

client_transfer_id

string

length ≤ 50

A client defined transfer identifier. This is the unique ID assigned to the transfer on your system. Max 50 characters.

source_currency_code

string

length between 3 and 5

^[A-Z]{3,5}$

Defaults to USD

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_code

string

required

length between 3 and 5

^[A-Z]{3,5}$

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_token

string

required

length between 36 and 45

^([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}$

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_token

string

length between 36 and 41

^(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}$

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_amount

float

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

source_amount

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

length between 36 and 45

^(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}$

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.

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

Defaults to false

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

auto_commit

boolean

Defaults to false

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

length ≤ 140

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_token

string

length between 36 and 40

^(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}$

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.

value_added_services

object

Optional per-transaction overrides for payout value added services. Omitted properties default to the account's configuration.

Headers

Idempotency-Key

string

Unique key to prevent duplicate processing

Responses

201Successfully created.

400Bad request.

401Unauthorized.

403Forbidden.

404Not found.

405Method Not Allowed.

500Internal server error.

504Gateway Time-out.