MAmasspay
Payout

Get history of payouts by user token

Changed on

This GET endpoint is used to retrieve the payout history for a user with the specified token. <br> You can use this endpoint to view all payouts made to a user, including the payout_token, destinantion_token and destination_amount. <br> To use this endpoint, you need to provide the user token of the recipient in the URL Path. <br> The response will include a JSON object containing an array of payout transactions for the specified user, with each transaction including details such as the transaction ID, payout amount, currency, payout status, and date and time of the payout.

get/payout/{user_token}

Request

Path parameters

user_tokenstring required
Example:usr_5b54fd79-2aa8-4965-85ed-0b3ad3739752

Token representing the user whose payout history is fetched. 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 parameters

include_payer_logosboolean
Example:true

Whether to include the payers logo in base64 format.

Headers

Idempotency-Keystring

Unique key to prevent duplicate processing

Response

successful operation

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

      for the path request parameter user_token, the minLength was increased from 0 to 36

    • breaking

      added the pattern ^(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}$ to the path request parameter user_token

    • 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

    • warning

      for the path request parameter user_token, the maxLength was set to 40

    • 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