Sign in

v1

latestOpenAPI 3.0.1Apache 2.02026-07-248286406.8 KB
Payout

Initiate a payout transaction

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}

Path parameters

user_tokenstring required

Token representing the user to pay out

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.

source_currency_codestring

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_codestring required

The currency the funds will be deposited into. Using ISO 4217 format

source_tokenstring uuid required

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

destination_tokenstring 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_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 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.

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.

Example request

{
  "client_transfer_id": "aEjn345",
  "source_currency_code": "USD",
  "destination_currency_code": "MXN",
  "source_token": "123e4567-e89b-12d3-a456-426614174000",
  "destination_token": "123e4567-e89b-12d3-a456-426614174000",
  "destination_amount": 100.5,
  "source_amount": 100.5,
  "attr_set_token": "123e4567-e89b-12d3-a456-426614174000",
  "metadata": {
    "group_id": 541
  },
  "statement_description": "Merchant 4561",
  "value_added_services": {
    "account_validation": {
      "validation": "SKIP"
    }
  }
}

Response

Successfully created.

OR

Example response

{
  "payout_token": "ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "client_transfer_id": "aEjn345",
  "source_currency_code": "USD",
  "destination_currency_code": "MXN",
  "source_token": "ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "destination_token": "d2138fd0-00be-45a8-985f-4f5bde500962",
  "destination_amount": 100.5,
  "source_amount": 100.5,
  "attr_set_token": "b1a867c1-6e36-4525-b6d5-a20bac80e3b0",
  "exchange_rate": 18.55,
  "fee": 2.99,
  "expiration": "2019-06-26T22:32:05",
  "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",
  "reversible_amount": 100.5
}