Send a payout
Quote a payment to a Beneficiary, accept one quote as a Payout, and follow it until the money arrives.
Sending money takes three calls. You ask for quotes, accept one of them, and follow the Payout it becomes until it is completed.
Quote
POST /v1/quotes prices the payment over every route that can deliver it.
Accept
POST /v1/payouts turns the quote you pick into a Payout.
Follow
GET /v1/payouts/{id} or the payout.updated webhook tells you where it stands.
Before you start
- Your account is
active. Until then every money route answerscustomer_not_active. See Onboarding. - Your API key holds
customer:payouts:create. To read Payouts back it also needscustomer:read. - The Beneficiary is registered and
verified. See Beneficiaries. - Your balance holds the send amount at the Provider where the route starts. See Balances and deposits.
Ask for quotes
You name what you send and to whom. You never send the destination: it is the Beneficiary's country and asset. The source country is your own.
Prop
Type
Tom, a US business, sends 1000 USDC to a supplier in the United Kingdom:
curl -X POST "$APEX_BASE_URL/v1/quotes" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source_asset": "USDC",
"amount": "1000",
"beneficiary_id": "6f1c2a9e-3b7d-4c58-9a21-0d4e8b7f5c13",
"purpose": "supplier"
}'The answer is 201 Created with a quote set:
{
"quote_set_id": "0b9d6c1e-7f2a-4e35-8c41-5a6b9e0d2f78",
"quotes": [
{
"quote_id": "qt1.eyJkIjoiMGI5ZDZjMWUtN2YyYS00ZTM1…",
"send": { "amount": "1000", "asset": "USDC" },
"receive": { "amount": "788.71", "asset": "GBP" },
"fees": [
{ "provider": "bvnk", "component": "provider", "amount": { "amount": "1", "asset": "USDC" } },
{ "provider": "bvnk", "component": "provider", "amount": { "amount": "0.5", "asset": "GBP" } }
],
"rates": [
{ "provider": "bvnk", "rate": "0.79" },
{ "provider": "bvnk", "rate": "1" }
],
"providers": ["bvnk"],
"settlement_seconds": 120,
"estimated_arrival": "2026-11-12T10:02:00Z",
"expires_at": "2026-11-12T10:01:00Z",
"labels": ["cheapest", "fastest"]
}
],
"server_time": "2026-11-12T10:00:00Z"
}What a quote holds
| Field | Meaning |
|---|---|
quote_id | The token you send back to accept this quote. Treat it as opaque: it is signed, and only your account can use it. |
send | What leaves your balance, fees included. |
receive | What the Beneficiary gets, after every fee. |
fees | Every fee as its own line, in the asset it is charged in. |
rates | Each Provider's rate, passed through unchanged, one line per step of the route. |
providers | The Providers that run the route, in order. |
settlement_seconds | How long the route's steps take together, as the Providers declare it. |
estimated_arrival | server_time plus settlement_seconds. An estimate, not a promise. |
expires_at | The last moment you can accept the quote. |
labels | cheapest marks the quote that delivers the most, fastest the one that arrives soonest. One quote can carry both. |
server_time is when the answer was made, in UTC. Count a quote's time left from it, not from your own clock.
Fees
Fees come in three components:
component | Who charges it |
|---|---|
service_fee | Our fee for the payment. It has no provider and is always in the send asset. It comes off the amount before the first step. |
provider | A Provider's fee for one step, in that step's input asset. |
network | A network fee a Provider passes on for one step. |
A quote is all-in: receive is what remains after every line. In the example above, the first step charges 1 USDC and converts the rest, 999 × 0.79 = 789.21 GBP. The payout step charges 0.5 GBP, so the Beneficiary receives 788.71 GBP.
Worked examples from the sandbox
The sandbox runs these corridors with fixed, illustrative rates and fees, and no service fee:
| You send | Beneficiary | Route | Beneficiary receives |
|---|---|---|---|
| 1000 USDC | DE, EUR | Conversion, then SEPA Instant | 918.58 EUR |
| 1000 EURC | DE, EUR | Conversion, then SEPA Instant | 998.5 EUR |
| 1000 USDC | GB, GBP | Conversion, then Faster Payments | 788.71 GBP |
| 1000 USDC | US, USD | Conversion, then RTP | 998 USD |
| 1000 USDT | PK, PKR (bank account) | Sold for USD in the US, then paid out in Pakistan | 277664.5 PKR |
For a German IBAN you get two quotes, SEPA Instant and SEPA Credit Transfer. Both deliver 918.58 EUR. Instant arrives in about two minutes, the credit transfer in about a day. When two quotes deliver the same amount, only one of them carries cheapest, so compare estimated_arrival too.
The US to Pakistan corridor shows how fees stack. Lina, a business in Pakistan, is Tom's Beneficiary. With a service fee of 0.5% plus 1 USDT, Tom's 1000 USDT become:
| Step | Calculation | Result |
|---|---|---|
| Service fee | 1000 × 0.5% + 1 = 6 USDT | 994 USDT left |
| Step 1, sold for USD | fee 1 USDT, rate 1 | 993 USD |
| Step 2, paid out in PKR | fee 2 USD, rate 278.5: 991 × 278.5 | 275993.5 PKR |
The quote lists three fee lines: service_fee for 6 USDT, then one provider line per step, for 1 USDT and 2 USD. Without a service fee the same payment delivers 277664.5 PKR.
Quote lifetime
A quote is short-lived: about a minute in the sandbox. Read expires_at on every quote and accept before it. After that, ask for a new quote.
Each quote can be accepted once. A second Payout from the same quote is refused with quote_already_used.
When no quote comes back
If nothing can carry the payment, quotes is empty and unavailable_reason says why in one word. The answer is still 201.
{
"quote_set_id": "5d2a8f0c-1e6b-4b7a-9c3d-8f4e2a1b6c90",
"quotes": [],
"unavailable_reason": "funds_at_other_provider",
"deposit_at": ["bvnk"],
"server_time": "2026-11-12T10:00:00Z"
}unavailable_reason | What it means | What to do |
|---|---|---|
beneficiary_not_verified | The Beneficiary is still pending_verification, is blocked, or is another Customer that cannot receive now. quote_set_id is absent. | Wait for beneficiary.updated to say verified, or pick another Beneficiary. |
onboarding_required | A Provider on every possible route has not approved your account yet. | Nothing to change in the request. Contact your account manager; the application may still be under review. |
funds_at_other_provider | You hold the amount, but at a different Provider than the routes start at. deposit_at names where to deposit. | Deposit the send asset at one of the deposit_at Providers, then quote again. See Balances and deposits. |
temporarily_unavailable | A route is closed for a while on our side. | Nothing to do. Retry later. |
amount_out_of_range | The amount is below or above what the routes take, or too small to cover the fees. | Try a different amount. |
no_route | No route serves this corridor or this Beneficiary now. | Contact your account manager. |
When several reasons apply, you get the one you can act on first, in this order: beneficiary_not_verified, onboarding_required, funds_at_other_provider, temporarily_unavailable, amount_out_of_range, no_route.
deposit_at comes only with funds_at_other_provider, and is never empty then. Its values are the same Provider keys that GET /v1/deposit-instructions and GET /v1/balances use.
If you hold the amount nowhere
funds_at_other_provider appears only when you already hold the amount at some Provider. If you hold it at none, you still get quotes, and the Payout waits for a deposit (see below). Fund your balance first, then quote.
Errors from POST /v1/quotes
| Code | Status | Cause |
|---|---|---|
validation_failed | 400 | A required field is missing, or purpose or preference has an unknown value. |
bad_amount | 422 | amount is not a positive decimal. |
amount_scale | 422 | amount has more decimals than the asset takes. |
beneficiary_not_found | 404 | No Beneficiary of yours has this id. |
customer_suspended | 403 | Your account is suspended and can only read. |
customer_not_active | 403 | Your account is not open yet, or is closed. |
A 5xx answer such as quote_unavailable or funds_unavailable means a Provider or a dependency did not answer in time. Retry with backoff. See Errors for the error format.
Accept a quote
Send the quote_id you picked to POST /v1/payouts. The Idempotency-Key header is required. Generate one key per Payout you mean to create, and send the same key again when you retry: a retry answers the first Payout instead of creating a second one. See Idempotency.
IDEMPOTENCY_KEY=$(uuidgen)
curl -X POST "$APEX_BASE_URL/v1/payouts" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $IDEMPOTENCY_KEY" \
-d '{ "quote_id": "qt1.eyJkIjoiMGI5ZDZjMWUtN2YyYS00ZTM1…" }'{
"id": "3c8e5b1a-9d24-4f6e-b7a0-2e1f4c6d8a95",
"state": "processing",
"send": { "amount": "1000", "asset": "USDC" },
"receive": { "amount": "788.71", "asset": "GBP" },
"fees": [
{ "provider": "bvnk", "component": "provider", "amount": { "amount": "1", "asset": "USDC" } },
{ "provider": "bvnk", "component": "provider", "amount": { "amount": "0.5", "asset": "GBP" } }
],
"rates": [
{ "provider": "bvnk", "rate": "0.79" },
{ "provider": "bvnk", "rate": "1" }
],
"beneficiary": {
"id": "6f1c2a9e-3b7d-4c58-9a21-0d4e8b7f5c13",
"name": "Northwind Supplies Ltd",
"country": "GB",
"party_type": "business"
},
"delivered_to": "bank_account",
"legs": [
{ "index": 0, "provider": "bvnk", "from": "USDC", "to": "GBP", "state": "pending" },
{ "index": 1, "provider": "bvnk", "from": "GBP", "to": "GBP", "state": "pending" }
],
"initiated_by": { "actor": "customer", "kind": "api_key", "id": "9a7b3c21-5d4e-4f60-8b19-c2d3e4f5a6b7" },
"initiated_by_you": true,
"cancellable": false,
"created_at": "2026-11-12T10:00:20Z",
"updated_at": "2026-11-12T10:00:20Z"
}The Payout keeps the quote's amounts, fees and rates. legs are the steps of the route, in order, each with its own state: pending, processing, completed, failed, returned or cancelled. delivered_to is bank_account, or balance when the route credits another Customer's platform balance (see Receiving payouts).
Which state comes back
state in the answer | Why |
|---|---|
processing | Your balance covered the send amount. It was held at once and the route started. |
accepted | Your balance at the route's first Provider does not cover the send amount yet. The Payout waits for a deposit there. |
awaiting_approval | One of your approval rules holds the Payout for a second person. Nothing is held from your balance yet. |
Errors from POST /v1/payouts
| Code | Status | Cause and what to do |
|---|---|---|
quote_token_invalid | 422 | The quote_id was altered, or belongs to another account. Use a quote_id exactly as a quote set answered it. |
quote_expired | 422 | The quote lapsed, or its route can no longer start. Ask for a new quote. |
quote_already_used | 409 | A Payout already exists for this quote. If this was your retry, send the original Idempotency-Key to get that Payout back. Otherwise quote again. |
beneficiary_changed | 409 | The Beneficiary is another Customer, and it changed the account it receives into after you quoted. Quote again; the new quote pays the new account. |
beneficiary_unavailable | 409 | The Beneficiary is another Customer that cannot receive now. Try later, or ask them to set a Receiving Account. |
beneficiary_not_verified | 422 | The Beneficiary was blocked or is no longer verified. |
customer_suspended | 403 | Your account is suspended. |
Follow the Payout
States
| State | What it means | Final |
|---|---|---|
awaiting_approval | Your approval rules hold it for a second person of your company. Nothing is held from your balance. It is cancelled if its quote expires first. | No |
accepted | Accepted, waiting for your balance at the route's first Provider to cover the send amount. Nothing is held yet. It is cancelled if its quote expires before it is funded. | No |
funded | The send amount, fees included, is held from your balance. It shows under held in GET /v1/balances. | No |
processing | The route's steps are running, including any compliance check. | No |
completed | The last step settled: the Beneficiary was paid. | Yes |
failed | A step failed. The amount stays held while our operations team retries the step or refunds the Payout. | No |
refunded | The held amount went back to your available balance. | Yes |
cancelled | Closed before anything was held. Nothing left your balance. | Yes |
GET /v1/payouts/{id} adds a timeline: each state the Payout reached, when, and by whom. by.actor is customer (your people or keys, with their kind and id), operations or system. When an approver lets a Payout through, the accepted entry names them.
{
"timeline": [
{ "state": "accepted", "at": "2026-11-12T10:00:20Z", "by": { "actor": "customer", "kind": "api_key", "id": "9a7b3c21-5d4e-4f60-8b19-c2d3e4f5a6b7" } },
{ "state": "funded", "at": "2026-11-12T10:00:20Z", "by": { "actor": "customer", "kind": "api_key", "id": "9a7b3c21-5d4e-4f60-8b19-c2d3e4f5a6b7" } },
{ "state": "processing", "at": "2026-11-12T10:00:20Z", "by": { "actor": "customer", "kind": "api_key", "id": "9a7b3c21-5d4e-4f60-8b19-c2d3e4f5a6b7" } },
{ "state": "completed", "at": "2026-11-12T10:02:05Z", "by": { "actor": "system" } }
]
}Waiting for approval
Your company's admins set approval rules in the Customer panel: a threshold amount per asset, the first Payout to a new Beneficiary, or both. When any rule matches, POST /v1/payouts answers awaiting_approval.
API keys never approve
A held Payout is approved or rejected by a person, in the Customer panel. That person needs the approver or admin role. They cannot be the person who started the Payout, nor the person who created the API key that started it. No API key can hold the approve permission, so your integration cannot approve its own Payouts.
What your integration sees:
- On approval the Payout moves to
acceptedand is funded at once if your balance covers it. - On rejection it moves to
cancelled; thecancelledtimeline entry isbythe person who rejected it. - If the quote expires before anyone approves, the Payout is cancelled by
system. Because quotes are short-lived, approvals must happen quickly; otherwise quote again and create a new Payout. - If, while it waited, the Beneficiary was blocked, the receiving Customer changed its account, or your account was suspended, the approval cancels the Payout instead.
Waiting for funds
A Payout in accepted waits for your balance at the route's first Provider to cover the send amount. A deposit there funds it, oldest Payout first. If the quote expires first, the Payout is cancelled. In practice: deposit first, then quote.
Cancelling
POST /v1/payouts/{id}/cancel closes a Payout that nothing has been held for yet: one in awaiting_approval or accepted. The Payout's cancellable field tells you whether the call is allowed now. Once a Payout is funded, the money is on its way and cancel answers payout_not_cancellable (409).
curl -X POST "$APEX_BASE_URL/v1/payouts/3c8e5b1a-9d24-4f6e-b7a0-2e1f4c6d8a95/cancel" \
-H "Authorization: Bearer $APEX_API_KEY"A cancelled Payout keeps its quote: to send again, ask for a new quote.
Failures and refunds
When a step fails, the Payout moves to failed and carries a failure:
{ "state": "failed", "failure": { "leg": 1, "code": "provider_refused" } }leg is the index of the step that failed. code is one of provider_refused (the Provider refused the step), rate_moved (the Provider's price moved more than allowed before the step was sent), leg_failed, leg_returned or leg_cancelled (the Provider reported the step failed, was returned or was cancelled), or no_connection (the Provider could not be reached).
You do not need to act. Our operations team either retries the step, and the Payout goes back to processing, or refunds it. A refund moves the Payout to refunded and returns the held amount to your available balance, at the Provider it was held at. A Provider fee that a completed step already charged in the send asset is not returned.
Polling or webhooks
Subscribe to the payout.updated webhook: you get the whole Payout every time its state changes, signed, and retried until your endpoint answers. See Webhooks.
If you poll instead, read GET /v1/payouts/{id} with a backoff, and stop at a final state: completed, refunded or cancelled. A failed Payout is not final.
To list Payouts, use GET /v1/payouts, newest first:
| Query parameter | Meaning |
|---|---|
state | One of the states above. processing lists every Payout whose route is running. |
limit | 1 to 100, default 50. |
cursor | The next_cursor of the previous page. next_cursor is absent on the last page. |
curl "$APEX_BASE_URL/v1/payouts?state=failed&limit=20" \
-H "Authorization: Bearer $APEX_API_KEY"