MAmasspay
Wallet

Transfer funds between wallets

Changed on

This POST endpoint transfers funds immediately from a source wallet to a destination wallet. <br> The source_token must refer to a wallet owned by the authenticated client (either a client wallet token or a user wallet token belonging to the client). <br> The destination_token can refer to any user wallet in the system, or to another client wallet that is linked to this client (e.g. a subclient or sister-client relationship — transfers to unrelated client wallets are not permitted). <br> Transfers between wallets of different currencies are supported; an FX exchange rate will be applied automatically. <br> Transfers are executed immediately upon request and are not reversible.

post/wallet/transfer

Request

Query parameters

dry_runboolean

When true, validates the transfer and returns a quote (including FX rate and fee) without actually moving any funds.

Headers

Idempotency-Keystring

Unique key to prevent duplicate processing

Request body

source_tokenstring required

Token representing the source wallet. Must be a wallet owned by the authenticated client (client wallet token or user wallet token belonging to this client).

destination_tokenstring required

Token representing the destination wallet. Can be any user wallet in the system or a linked client wallet (subclient or sister-client). Transfers to unrelated client wallets are not permitted.

amountnumber required

Amount to transfer, denominated in the source wallet's currency. Up to 5 decimal places; a value with more is rejected.

client_transfer_idstring

Optional client-provided identifier for this transfer. Useful for idempotency and reconciliation.

notesstring

Optional human-readable note or description for this transfer.

metadataobject

Optional arbitrary key-value metadata to attach to the transfer.

Example request

{
  "source_token": "clnt_wlt_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "destination_token": "usr_wlt_123e4567-e89b-12d3-a456-426614174000",
  "amount": 100.5,
  "client_transfer_id": "aEjn345",
  "notes": "Bonus payment for Q2",
  "metadata": {
    "group_id": 541
  }
}

Response

Successfully created.

transfer_tokenstring required

Unique token identifying this transfer (load prefix, since a transfer is recorded as a ledger load).

source_tokenstring required

Token of the source wallet.

destination_tokenstring required

Token of the destination wallet.

source_amountnumber required

Amount debited from the source wallet, in the source currency.

destination_amountnumber required

Amount credited to the destination wallet, in the destination currency. May differ from source_amount when an FX conversion is applied.

source_currency_codestring required

Currency of the source wallet. Using ISO 4217 format.

destination_currency_codestring required

Currency of the destination wallet. Using ISO 4217 format.

exchange_ratenumber

FX exchange rate applied to convert between currencies. Present only when source and destination currencies differ.

feenumber

Fee charged for the transfer, in the source currency.

status'COMPLETED' | 'QUOTE' required

Status of the transfer. Transfers are immediate, so this will always be COMPLETED unless dry_run was requested.

client_transfer_idstring

Client-provided identifier echoed back from the request.

notesstring

Note or description echoed back from the request.

metadataobject

Metadata echoed back from the request.

created_atstring date-time required

Timestamp of when the transfer was created.

Example response

{
  "transfer_token": "ld_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "source_token": "clnt_wlt_ba4275f2-bae1-488d-9d6f-20af1cd83574",
  "destination_token": "usr_wlt_123e4567-e89b-12d3-a456-426614174000",
  "source_amount": 100.5,
  "destination_amount": 1865.28,
  "source_currency_code": "USD",
  "destination_currency_code": "MXN",
  "exchange_rate": 18.56,
  "status": "COMPLETED",
  "client_transfer_id": "aEjn345",
  "notes": "Bonus payment for Q2",
  "metadata": {
    "group_id": 541
  },
  "created_at": "2024-07-21T17:32:28Z"
}

Changes