Sign in

v1

latestOpenAPI 3.0.1Apache 2.02026-07-248286406.8 KB
Payout

Get status of a payout by payout token

This GET endpoint is used to retrieve the status of a payout transaction for a user with the specified token and payout token. <br> You can use this endpoint to check the status of a specific payout transaction, including whether the payout has been successfully processed or if there was an error. <br> To use this endpoint, you need to provide the user_token and payout_token in the URL Path. <br> The response will include a JSON object containing details about the payout transaction.

get/payout/{user_token}/{payout_token}

Query parameters

force_status_updateboolean
Example:true

Attempts to get an updated status update from the payout destination

include_payer_logoboolean

Whether to include the payer logo in base64 format.

Headers

Idempotency-Keystring

Unique key to prevent duplicate processing

Response

OK

payout_tokenstring 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_idstring required

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

source_currency_codestring required

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. your bank account, user's 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 required

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

source_amountnumber 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_tokenstring 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_ratenumber float required

The exchange rate to convert source_amount to destination_amount

feenumber float required

Fee to be charged for the transaction

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

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_logostring byte

base64 representation of the payer logo

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

Country code ISO_3166

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.

estimated_availabilitystring date-time required

Estimated availability of funds. When funds would be available to pickup/deposited

status_reasonstring

Optional. Contains the reason for the status change. Most commonly used for CANCELLED status with the reason for cancellation

attrsobject

The relevant attributes that were used to fulfill this payout

reversible_amountnumber 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.

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
}