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

Token representing the user to pay out

Query Params

limit

number

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

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

source_currency_code

string

Defaults to USD

The currency originating balance is stored in. Using 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 format

source_token

uuid

required

Token that represents the funding source i.e. bank account, wallet. 36 characters long

destination_token

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

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

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

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.

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.