Skip to Content
Apex Settlement

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 answers customer_not_active. See Onboarding.
  • Your API key holds customer:payouts:create. To read Payouts back it also needs customer: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:

201 Created
{
  "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

FieldMeaning
quote_idThe token you send back to accept this quote. Treat it as opaque: it is signed, and only your account can use it.
sendWhat leaves your balance, fees included.
receiveWhat the Beneficiary gets, after every fee.
feesEvery fee as its own line, in the asset it is charged in.
ratesEach Provider's rate, passed through unchanged, one line per step of the route.
providersThe Providers that run the route, in order.
settlement_secondsHow long the route's steps take together, as the Providers declare it.
estimated_arrivalserver_time plus settlement_seconds. An estimate, not a promise.
expires_atThe last moment you can accept the quote.
labelscheapest 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:

componentWho charges it
service_feeOur fee for the payment. It has no provider and is always in the send asset. It comes off the amount before the first step.
providerA Provider's fee for one step, in that step's input asset.
networkA 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 sendBeneficiaryRouteBeneficiary receives
1000 USDCDE, EURConversion, then SEPA Instant918.58 EUR
1000 EURCDE, EURConversion, then SEPA Instant998.5 EUR
1000 USDCGB, GBPConversion, then Faster Payments788.71 GBP
1000 USDCUS, USDConversion, then RTP998 USD
1000 USDTPK, PKR (bank account)Sold for USD in the US, then paid out in Pakistan277664.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:

StepCalculationResult
Service fee1000 × 0.5% + 1 = 6 USDT994 USDT left
Step 1, sold for USDfee 1 USDT, rate 1993 USD
Step 2, paid out in PKRfee 2 USD, rate 278.5: 991 × 278.5275993.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.

201 Created
{
  "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_reasonWhat it meansWhat to do
beneficiary_not_verifiedThe 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_requiredA 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_providerYou 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_unavailableA route is closed for a while on our side.Nothing to do. Retry later.
amount_out_of_rangeThe amount is below or above what the routes take, or too small to cover the fees.Try a different amount.
no_routeNo 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

CodeStatusCause
validation_failed400A required field is missing, or purpose or preference has an unknown value.
bad_amount422amount is not a positive decimal.
amount_scale422amount has more decimals than the asset takes.
beneficiary_not_found404No Beneficiary of yours has this id.
customer_suspended403Your account is suspended and can only read.
customer_not_active403Your 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…" }'
201 Created
{
  "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 answerWhy
processingYour balance covered the send amount. It was held at once and the route started.
acceptedYour balance at the route's first Provider does not cover the send amount yet. The Payout waits for a deposit there.
awaiting_approvalOne of your approval rules holds the Payout for a second person. Nothing is held from your balance yet.

Errors from POST /v1/payouts

CodeStatusCause and what to do
quote_token_invalid422The quote_id was altered, or belongs to another account. Use a quote_id exactly as a quote set answered it.
quote_expired422The quote lapsed, or its route can no longer start. Ask for a new quote.
quote_already_used409A 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_changed409The 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_unavailable409The Beneficiary is another Customer that cannot receive now. Try later, or ask them to set a Receiving Account.
beneficiary_not_verified422The Beneficiary was blocked or is no longer verified.
customer_suspended403Your account is suspended.

Follow the Payout

States

StateWhat it meansFinal
awaiting_approvalYour 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
acceptedAccepted, 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
fundedThe send amount, fees included, is held from your balance. It shows under held in GET /v1/balances.No
processingThe route's steps are running, including any compliance check.No
completedThe last step settled: the Beneficiary was paid.Yes
failedA step failed. The amount stays held while our operations team retries the step or refunds the Payout.No
refundedThe held amount went back to your available balance.Yes
cancelledClosed 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 of a completed Payout
{
  "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 accepted and is funded at once if your balance covers it.
  • On rejection it moves to cancelled; the cancelled timeline entry is by the 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 parameterMeaning
stateOne of the states above. processing lists every Payout whose route is running.
limit1 to 100, default 50.
cursorThe 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"

Next steps

On this page