Initiate a payin transaction

post

https://{environment}.masspay.io/{VERSION}/payin/{user_token}

This POST endpoint initiates a pay-in transaction from a user to your account.
Use this endpoint to collect funds from users — for example, deposits, payments, or wallet top-ups.
Provide the payer's user_token in the URL path, and include in the request body the source of funds (source_token), deposit destination (destination_token), and the currency of the pay-in (source_currency_code).
The response returns complete details of the pay-in transaction, including status, amounts, and references.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

user_token

string

required

Token representing the user to pay out

Body Params

Pay-in parameters

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

required

Currency from which the pay-in originates — the currency in which funds are collected (ISO 4217 for fiat, e.g. USD; may include network suffix for crypto, e.g. USDT_ERC20; for cards, this is the currency charged to the payer’s card).

destination_currency_code

string

The currency that will be loaded into your MassPay wallet. In ISO 4217 format. It needs to match the currency of the destination_token

destination_token

uuid

Token representing the destination wallet - where the pay-in funds will be credited, either into the user's wallet or the client's wallet. If none is provided, it will deposit into the client wallet with destination_currency. If such wallet does not already exist, it will be auto-created.

source_token

uuid

required

Token that represent the rail through which the pay-in will be collected from. I.e. Crypto Deposit, Cash Deposit, Bank Debit, etc. List of available service can be obtained through the catalog pay-ins endpoint

attr_set_token

uuid

Token that represent the funding account that will be used for the pay-in transaction. Only required for pull transactions. For push transactions, like Cash Deposit or Crypto Deposit, this is an optional field. For Crypto Deposits, if attr_set_token is provided, deposits will only be accepted if they originated from the provided wallet address.

source_amount

float

≥ 0

The amount to be collected from the source_token in source_currency. i.e USDT. Must be provided if destination_amount is empty

destination_amount

float

≥ 0

The amount to be deposited into the destination_token in destination_currency. i.e USD. Must be provided if source_amount is empty

metadata

object

Optional JSON object with attributes that can later be searched to locate this pay-in. 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.

statement_description

string

Optional descriptive line item that appears on the pay-in statement, providing details about the transaction. This field is intended to help identify the purpose or source of each pay-in by displaying a brief summary or itemized description. Commonly includes information such as transaction type, merchant name, or payin 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.