Submit a payout order to send money to a beneficiary.
POST
/api/v1/payments/order
subscribe to webhooks for the outcome. Send
X-Idempotency-Key to make retriessafe; without it the server generates a key per request, which gives no de-duplication
across retries. Include the
quoteId from a prior quote to settle at a locked rate.beneficiaryId.X-Idempotency-Key — a distinct value per logical attempt, reused only when retrying the same attempt. Without it, a network retry can create a duplicate payout.GET /api/v1/payments/order/{orderId} for the outcome.POST /api/v1/payments/quote; fund a crypto-backed order via GET .../getdepositaddress/{orderId}.⚠️ Required Fields
| Field | Type | Description | Constraints |
|---|---|---|---|
beneficiaryId | string (uuid) | Who is being paid. Named to match the /beneficiaries resource and the beneficiaryId route parameter; the legacy contract called this "payeeId". | — |
source | object | The debit side of a payout order. | — |
source.amount | number (double) | Amount to send, in the source wallet's currency. The legacy contract called this "requestedAmount"; the qualifier carried no meaning the grouping does not already give. | min 0.0001 |
Optional Fields
| Field | Type | Description | Constraints |
|---|---|---|---|
productId | string (uuid) | The payout product. Determines the corridor and which provider executes the payout. | nullable |
quoteId | string | Quote id from a prior POST v1/quotes call. Supply it when the corridor requires a locked rate, so the order settles at the price the quote returned. | nullable |
source.currency | string | The crypto currency the payout is funded from, as an asset code (e.g. "USDT") — not a wallet id. This surface deliberately takes no wallet id: partners on it have not taken the wallets module, so their customers own no wallet rows to name. The funding wallet is the tenant's pooled row for this currency (Member.CustomerWalletMaster.IsMerchantAccount = 1); its id and its available balance are both resolved server-side from the code sent here, which is why the legacy "customerWalletId" field is gone rather than merely optional. Optional. When omitted the payout product's own asset code is used, so a partner that only ever pays out in the product's asset need not send it. When supplied it must BE the product's asset: a code naming a different asset is rejected rather than debiting a pooled wallet other than the one the order is priced and executed against. | nullable |
destination | object | The credit side of a payout order. | — |
destination.currency | string | ISO currency the beneficiary receives. The legacy contract called this "fiatCurrency", which named an implementation detail rather than the party it describes. | nullable |
payment | object | How the payout is routed to the beneficiary. | — |
payment.type | string | Payment method for the payout leg. | nullable |
compliance | object | Regulatory context for the transfer. Codes come from the lookup endpoints — purpose from GET v1/purpose/{currency}, source of funds from GET v1/sourceoffunds, and relationship from GET v1/relationships. | — |
compliance.purposeCode | string | Why the payment is being made (e.g. "payment_for_services"). | nullable |
compliance.sourceOfFundsCode | string | Where the funds originated (e.g. "advance_from_shareholder"). | nullable |
compliance.beneficiaryRelationship | string | The sender's relationship to the beneficiary. | nullable |
📤 Response Fields
| Field | Type | Nullable | Description |
|---|---|---|---|
data | object | No | Result of creating a payout order. |
data.transactionId | string (uuid) | No | Our internal order id. Use this to poll GET /order/{orderId} or match webhook events. |
data.txId | string | Yes | Provider-side transaction reference, if assigned synchronously at submission time. |
data.status | string | Yes | Initial order status immediately after submission — typically pending or processing. See the status table above. |
data.amount | number (double) | Yes | Amount accepted for the order, in the source currency. |
data.createdAt | string (date-time) | Yes | When the order was created. |
requestId | string | Yes | — |
timestamp | string (date-time) | No | — |
Request
Query Params
Header Params
Body Params
application/json-patch+json
Responses
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location '/api/v1/payments/order?customerId=c1f4a9d2-6b3e-4a7c-9f1d-2e8b5c0a7d31' \
--header 'X-Idempotency-Key: 6f1a9c0e-2b7d-4c31-9f8a-1d5e7c3b0a42' \
--header 'X-API-Key: ak_live_8f3a9b2c7e1d4f6a9b0c2d5e8f1a3b6c' \
--header 'X-Signature: kZ3fQeT2m7xVvC9pR1sLdY8bN0hU4jK6oW5aE2gI7cQ=' \
--header 'X-Timestamp: 1758556800' \
--header 'X-Nonce: 3fa85f64-5717-4562-b3fc-2c963f66afa6' \
--header 'X-Body-Hash: 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=' \
--header 'Content-Type: application/json-patch+json' \
--data '{
"productId": "b4d1e7f2-3a9c-4e6b-8d0a-1f7c2b9e4a63",
"quoteId": "qte_9a3f7c1e5b8d4a2f6c0e3b9d1a7f5c8e",
"beneficiaryId": "e9c2a7d4-5b8f-4c1e-9a3d-6f0b1c8e2d47",
"source": {
"currency": "USDT",
"amount": 5000
},
"destination": {
"currency": "EUR"
},
"payment": {
"type": "bank_transfer"
},
"compliance": {
"purposeCode": "payment_for_services",
"sourceOfFundsCode": "business_revenue",
"beneficiaryRelationship": "supplier"
}
}'Response Response Example
202 - Success
{
"data": {
"transactionId": "7a2e4c9b-1f6d-4a3e-8c7b-9d0f2a5e6b18",
"txId": null,
"status": "pending",
"amount": 5000,
"createdAt": "2026-09-22T14:02:47Z"
},
"requestId": "req_4f9a2c7e1b8d3f6a9c2e0b7d1f8a3c6e",
"timestamp": "2026-09-22T14:03:11Z"
}Modified at 2026-09-22 10:35:55