MAmasspay
Payin

Initiate a payin transaction

Changed on

This POST endpoint initiates a pay-in transaction from a user to your account. <br> Use this endpoint to collect funds from users - for example, deposits, payments, or wallet top-ups. <br> 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). <br> The response returns complete details of the pay-in transaction, including status, amounts, partner network response, and any required follow-up action. <br><br> Important: A 201 response indicates the request was accepted and processed. Inspect the response body's status and error fields to determine the actual outcome. A pay-in may be INITIATED (awaiting user action), PROCESSING (in flight), COMPLETED (funds delivered), or ERROR (declined by partner or validation failure).

post/payin/{user_token}

Request

Path parameters

user_tokenstring required

Token representing the user to pay out

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

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_codestring

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_tokenstring 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_tokenstring 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_tokenstring 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_amountnumber float

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

destination_amountnumber float

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

statement_descriptionstring

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.

Example request

{
  "value_added_services": {
    "cvv": "123",
    "avs": "RUN_AND_VALIDATE",
    "ani": "RUN_AND_VALIDATE",
    "three_ds": {
      "cavv": "jJ81HADVRtXfCBATEp01CJUAAAA=",
      "eci": "05",
      "ds_transaction_id": "f38e6948-5388-41a6-bca4-b49723c19437"
    }
  },
  "client_transfer_id": "Invoice531",
  "source_currency_code": "USDC",
  "destination_currency_code": "USD",
  "source_amount": 100.5,
  "destination_amount": 100.5,
  "statement_description": "Invoice #531"
}

Response

Pay-in request accepted. Inspect the body's status and error fields to determine the actual outcome (approved, processing, awaiting user action, or declined).

payin_tokenstring nullable

Token representing the initiated pay-in transaction. Use this for subsequent commit/status calls.

funding_codestring nullable

Funding code for tracking the payment source (e.g. cash deposit reference shown to the user).

client_transfer_idstring

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.

destination_tokenstring

Token representing the destination wallet/account where funds will be deposited.

payment_referencestring nullable

Payment reference identifier from the partner/network.

required_action'CASH_DEPOSIT_AT_STORE' | 'TRANSFER' | 'BANK_AUTHORIZATION' | 'CARD_CAPTURE' | 'NONE'

Additional action required from the user/system to complete the pay-in. NONE means no further action is needed.

instructionsstring

Human-readable instructions for completing the required action.

status'INITIATED' | 'PROCESSING' | 'COMPLETED' | 'ERROR' | 'CANCELLED'

Current status of the pay-in. INITIATED = created and awaiting action; PROCESSING = in flight at partner; COMPLETED = funds settled; ERROR = failed.

requires_commitboolean

Whether a separate commit call is required to finalize the transaction.

source_amountnumber double nullable

Amount in source currency.

destination_amountnumber double nullable

Amount in destination currency (after FX, if applicable).

exchange_ratenumber double nullable

Exchange rate applied between source and destination currencies.

feenumber double nullable

Fee charged for the pay-in, in source currency.

source_currency_codestring nullable

Source currency code (ISO 4217, or asset code for crypto).

destination_currency_codestring nullable

Destination currency code (ISO 4217, or asset code for crypto).

errorstring nullable

Error message when the pay-in fails. Format for partner failures: '<reason> [<action_code>] <network message>'.

error_type'VALIDATION' | 'PARTNER' | 'GENERIC' nullable

Category of the error. VALIDATION = client request issue; PARTNER = upstream partner/network failure; GENERIC = unclassified.

source_tokenstring

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

Example response

{
  "payin_token": "payin_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "funding_code": "CASH-9F2J7L",
  "destination_token": "clnt_wlt_fd407907-4913-4a99-b653-5e868743a692",
  "payment_reference": "REF-2025-04823",
  "instructions": "Commit payin to finalize transaction",
  "source_amount": 100.5,
  "destination_amount": 100.5,
  "fee": 2.99,
  "source_currency_code": "USD",
  "destination_currency_code": "USD",
  "network_response": {
    "action_code": "00",
    "approval_code": "123456",
    "address_verification": "Y",
    "cvv2_result_code": "M",
    "cavv_result_code": "2",
    "ani_result": "MATCH",
    "account_number": "1234567890",
    "routing_number": "021000021",
    "swift_bic": "CSRVUS33XXX",
    "bank_name": "Cross River Bank",
    "bank_address": "885 Teaneck Road, Teaneck, NJ 07666 USA",
    "name_on_account": "Jane Doe",
    "network_id": "VISA",
    "response_reason_code": "00"
  },
  "deposits": [
    {
      "token": "payin_dep_1f7c9a2e-3b41-4c8d-9e5f-8a6b2c4d7e90",
      "deposit_amount": 0.0025,
      "deposit_currency": "BTC",
      "fiat_amount": 100.5,
      "fiat_currency": "USD",
      "metadata": {
        "method": "wire",
        "account": "5500312884",
        "routing": "123456780",
        "name": "MARIA RIVERA",
        "imad": "20260914L1B7761R001532",
        "omad": "20260914FTB2007301846209141412FT01",
        "sender_reference": "8812045371XK",
        "beneficiary_reference": "INV 2026-0914-17",
        "originator_to_beneficiary": [
          "ORDER 48213 ACME WIDGETS"
        ]
      },
      "return_reason_code": "REFUSED_BY_BENEFICIARY",
      "network_return_code": "R23",
      "return_fee": 15
    }
  ],
  "error": "Insufficient funds or limit exceeded [51] Not sufficient funds"
}

Changes