MAmasspay
Payout

Get status of a payout by payout token

Changed on

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}

Request

Query parameters

force_status_updateboolean
Example:true

Attempts to get an updated status from the payout destination before responding. When the destination answers, the payout.status webhook is sent whether or not the status changed; a changed status is also written. Leave it unset when you only need the stored state. Never set it from inside a webhook handler: the handler would send itself the next event.

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 required

Token that represents the transaction that was just created. Returned either as a bare UUID or prefixed with payout_; both forms reference the same payout. Needs to be used to commit the transaction in /payout/{user_token}/{payout_token}. Always a token: 36 characters long, or 43 with the payout_ prefix. A duplicate client_transfer_id or insufficient funds in the source_token is not reported here but as 400 Bad request, with the cause in error.details — for example Duplicate client id. Existing payout token: payout_<uuid> or Non sufficient funds in source token.

client_transfer_idstring required

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 required

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 used for this payout, i.e. your bank account or the user's wallet. Returned 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 required

Token that represents the payout destination, i.e. MassPay->Brazil->Bank Deposit->Itau. To be retrieved from the #pricing callback. Returned either as a bare UUID or prefixed with dest_; both forms reference the same destination. 36 characters long, or 41 with the dest_ prefix.

destination_amountnumber float required

The amount to be sent for payout in destination currency. 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 required

Token that represents the set of attributes associated with the destination_token, for example a bank account, mobile account, or wallet id. Returned either as a bare UUID or prefixed with attr_set_; both forms reference the same attribute set. If not provided in the request, the last one used is applied. 36 characters long, or 45 with the attr_set_ prefix.

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 date-time required

The time and date at which the transaction will expire, returned in UTC (RFC 3339) with millisecond precision, e.g. 2026-08-22T17:40:46.881Z. 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. The reason for a CANCELLED or ERROR status, as text for people rather than a code: for example Requested cancellation, Validation error, Payer no longer available, a bank return code and description such as R01 - Insufficient Funds, or the validation message that rejected the payout. Display or log it, but do not branch on it.

attrsobject

The relevant attributes that were used to fulfill this payout

sender_user_tokenstring

Token that represents the user who is the sender (originator) of this payout, returned either as a bare UUID or with the usr_ prefix. Only returned when the payout was initiated on behalf of a sender and the transaction was not originated with the client as the sender. If absent, the client is the sender of record. 36 characters long, or 40 with the usr_ prefix.

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": "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

  • f9fa41b7c45cRevision changes
    • 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

    • 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