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