Skip to main content
POST
Wallet → Wallet (internal transfer)

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

Move funds to another wallet on your platform (intent_type=transfer).

A wallet-to-wallet transfer is user-to-user: it moves money from the source wallet (wallet_id) to another user's wallet (destination_wallet_id) on the same platform. Both wallets must belong to your platform — cross-platform transfers are not allowed. The master wallet may be on either side. No KYC/KYB is required to transfer between wallets.

wallet_id
string<uuid>
required

Source wallet UUID — the tenant's master wallet or one of the user's wallets. Server validates tenant ownership and currency and resolves the owner from it.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

amount
number
required

Amount in major currency units (e.g. dollars).

Example:

100.5

idempotency_key
string
required

Unique key to ensure idempotent payment creation.

Required string length: 1 - 120
Example:

"pay_req_20260604_abc123"

destination_wallet_id
string<uuid>
required

Destination wallet UUID to credit — another user's wallet (or your master wallet) on the same platform. The server validates tenant ownership and currency and resolves the owner from it.

Example:

"c3d4e5f6-a7b8-9012-3456-7890abcdef01"

user_id
string<uuid> | null

Optional safety cross-check — when sent, must match the owner of wallet_id.

Example:

"b3a9b622-cc63-4d3c-aad6-2d8e29e6f9d4"

currency
string
default:USD

ISO 4217 currency code.

Required string length: 3
Example:

"USD"

payment_type
enum<string> | null

Optional movement classification. transfer moves your own money (e.g. a bank deposit into your own wallet); send pays another party (e.g. a wallet → bank payout). When omitted the server derives it from the source and destination. When provided it is validated against them and rejected on mismatch.

Available options:
transfer,
send
Example:

"transfer"

metadata
Metadata · object

Arbitrary key-value metadata to attach to the payment.

Example:
payment_category
integer | null

Optional. The payment category code to tag this payment with, recording what the payment was for. Omit it and the payment is created exactly as before, untagged. If you do send one it must be a code your platform can currently use, otherwise the request is rejected and no money moves. Fetch the codes from GET /v1/platform/catalog/payment-categories. Codes are issued separately in test and live, so read the list in each mode — the same number does not mean the same category across them.

Required range: x > 0
Example:

1

from_hold
boolean
default:false

Draw this transfer from the source wallet's frozen (held) funds instead of its available balance. The held balance must cover the amount plus any payer-borne fee, or the request is rejected with insufficient_held_funds. Omit for a normal transfer from available balance.

Example:

false

Response

Successful Response

Standard response wrapper for single-object responses and errors.

Generic over the payload type. A route that declares CommonResponse[SomeModel] gets the real data schema rendered in OpenAPI/Swagger; a bare CommonResponse leaves data untyped.

status_code
integer
required

HTTP status code for the response.

data
any
required

Payload or error details.

query_generated_time
integer
required

UTC timestamp (milliseconds since epoch) when response was generated.