Skip to Content
Apex Settlement

Quickstart

Send your first sandbox payout, from an API key to a completed Payout.

This guide sends 1000 USDC from your sandbox balance to a company in Germany, which receives 918.58 EUR. It takes six calls. You need a sandbox account whose standing is active and a person on it with the Customer admin role.

Set two environment variables first. The sandbox base URL comes with your account.

Shell
export APEX_BASE_URL="<your sandbox base URL>"
export APEX_API_KEY="ak_test_..."

Get a test key

In the Customer panel, open API keys and choose Create key. Give it a name such as Quickstart and these permissions:

  • Read balances, payouts and beneficiaries (customer:read)
  • Create and cancel payouts (customer:payouts:create)
  • Register beneficiaries (customer:beneficiaries:write)

The key is shown once, as ak_test_ followed by two random parts. Store it in your secret store, then check that it works:

curl "$APEX_BASE_URL/v1/customer" \
  -H "Authorization: Bearer $APEX_API_KEY"
200 OK
{
  "id": "5f8c2a91-3e4b-4d6a-9c1f-7b2e8d4a6c30",
  "legal_name": "Tom Trading Inc",
  "type": "business",
  "country": "US",
  "standing": "active",
  "providers": ["bvnk", "zerohash"],
  "kind": "direct"
}

providers lists the Providers that have approved your account. A route can only use those Providers.

Check your balance

curl "$APEX_BASE_URL/v1/balances" \
  -H "Authorization: Bearer $APEX_API_KEY"
200 OK
[
  {
    "asset": "USDC",
    "available": "1000",
    "held": "0",
    "held_at": [{ "provider": "bvnk", "available": "1000", "held": "0" }]
  }
]

available is what you can send now. held is set aside for Payouts on their way. held_at splits each balance by the Provider that holds it. A Payout is paid from one Provider's part only, so the routes you are offered depend on where your money is. See Balances and deposits.

Funding your sandbox balance

GET /v1/deposit-instructions?asset=USDC tells you where to deposit. In sandbox the Providers are simulated and the addresses are placeholders, so nothing sent to them arrives. Ask your account team to credit test funds to your sandbox balance.

Create or pick a Beneficiary

List the Beneficiaries you already have and pick one whose state is verified, with the country and currency you want to pay:

curl
curl "$APEX_BASE_URL/v1/beneficiaries" \
  -H "Authorization: Bearer $APEX_API_KEY"

Or register a new one. A company in Germany paid in euro needs iban and name in details:

curl -X POST "$APEX_BASE_URL/v1/beneficiaries" \
  -H "Authorization: Bearer $APEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "external",
    "party_type": "business",
    "name": "Muster GmbH",
    "country": "DE",
    "asset": "EUR",
    "details": { "iban": "DE89370400440532013000", "name": "Muster GmbH" }
  }'
201 Created
{
  "id": "c1e7b3a9-4d2f-4a6e-8b05-9f3d2c7e1a84",
  "kind": "external",
  "state": "pending_verification",
  "party_type": "business",
  "name": "Muster GmbH",
  "country": "DE",
  "asset": "EUR",
  "details": { "iban": "••••3000", "name": "Muster GmbH" },
  "available": true,
  "created_at": "2026-11-12T09:41:07Z",
  "updated_at": "2026-11-12T09:41:07Z"
}

The details a destination needs follow its country and currency: iban and name for euro in a SEPA country, account_number, sort_code and name for pounds in GB, account_number, routing_number and name for dollars in the US. A field no route to that destination asks for is refused with beneficiary_fields_invalid. Account numbers come back masked to their last four characters. See Beneficiaries for every kind and destination.

New Beneficiaries wait for review

A Beneficiary you register starts in pending_verification. Our compliance team verifies it, in sandbox too, and you can pay it once its state is verified. Subscribe to beneficiary.updated to hear about it as soon as it happens.

Ask for quotes

Send the amount, the asset it leaves your balance in, the Beneficiary and the purpose of the payment. The destination country and currency are the Beneficiary's, so you do not send them.

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": "c1e7b3a9-4d2f-4a6e-8b05-9f3d2c7e1a84",
    "purpose": "services",
    "preference": "fastest"
  }'

Prop

Type

The sandbox offers two routes to a German IBAN: SEPA Instant and SEPA Credit Transfer. Both deliver 918.58 EUR; SEPA Credit Transfer takes about a day longer. The response below is trimmed to the first Quote.

201 Created
{
  "quote_set_id": "6e2a9c4f-8b1d-4f37-a5c2-1d9e7b3f0a52",
  "quotes": [
    {
      "quote_id": "qt1.eyJkIjoiNmUyYTljNGYtOGIxZC00ZjM3...",
      "send": { "amount": "1000", "asset": "USDC" },
      "receive": { "amount": "918.58", "asset": "EUR" },
      "fees": [
        { "provider": "bvnk", "component": "provider", "amount": { "amount": "1", "asset": "USDC" } },
        { "provider": "bvnk", "component": "provider", "amount": { "amount": "0.5", "asset": "EUR" } }
      ],
      "rates": [
        { "provider": "bvnk", "rate": "0.92" },
        { "provider": "bvnk", "rate": "1" }
      ],
      "providers": ["bvnk"],
      "settlement_seconds": 120,
      "estimated_arrival": "2026-11-12T10:02:00Z",
      "expires_at": "2026-11-12T10:01:00Z",
      "labels": ["fastest"]
    }
  ],
  "server_time": "2026-11-12T10:00:00Z"
}

Read the numbers Leg by Leg: the conversion takes a 1 USDC fee, so 999 USDC is converted at 0.92 into 919.08 EUR, and the SEPA Instant payout takes 0.5 EUR. The Beneficiary receives 918.58 EUR. Every fee is in the asset its Leg takes. A service_fee line appears when your pricing includes our fee.

labels marks the Quote that delivers the most (cheapest) and the one that settles soonest (fastest). A Quote is valid until expires_at, about a minute in sandbox. Count the time left from server_time, not from your own clock.

When no Quote can be offered, the call still answers 201 with an empty quotes list and an unavailable_reason:

unavailable_reasonWhat to do
beneficiary_not_verifiedWait until the Beneficiary is verified.
onboarding_requiredA Provider on every route has not approved your account yet. Contact your account team.
funds_at_other_providerYou hold the amount, but not at the Provider the routes start from. Deposit at a Provider listed in deposit_at.
amount_out_of_rangeThe amount is outside what the routes take. Try another amount.
temporarily_unavailableThe route is paused for a while. Try again later.
no_routeNo route can take this payment.

Accept a quote

Create a Payout from the quote_id before it expires. Send an Idempotency-Key header: a value you generate once for this payout and send again, unchanged, on every retry. See Idempotency.

curl -X POST "$APEX_BASE_URL/v1/payouts" \
  -H "Authorization: Bearer $APEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f6c1d2e-8a4b-4c9d-b1e7-5a2f9c8d0e13" \
  -d '{ "quote_id": "qt1.eyJkIjoiNmUyYTljNGYtOGIxZC00ZjM3..." }'
201 Created
{
  "id": "7d41f0b2-9c3e-4a85-b6d1-2e8f5a7c9b13",
  "state": "processing",
  "send": { "amount": "1000", "asset": "USDC" },
  "receive": { "amount": "918.58", "asset": "EUR" },
  "fees": [
    { "provider": "bvnk", "component": "provider", "amount": { "amount": "1", "asset": "USDC" } },
    { "provider": "bvnk", "component": "provider", "amount": { "amount": "0.5", "asset": "EUR" } }
  ],
  "rates": [
    { "provider": "bvnk", "rate": "0.92" },
    { "provider": "bvnk", "rate": "1" }
  ],
  "beneficiary": {
    "id": "c1e7b3a9-4d2f-4a6e-8b05-9f3d2c7e1a84",
    "name": "Muster GmbH",
    "country": "DE",
    "party_type": "business"
  },
  "delivered_to": "bank_account",
  "legs": [
    { "index": 0, "provider": "bvnk", "from": "USDC", "to": "EUR", "state": "pending" },
    { "index": 1, "provider": "bvnk", "from": "EUR", "to": "EUR", "state": "pending" }
  ],
  "initiated_by": { "actor": "customer", "kind": "api_key", "id": "a3d9e1f4-6b2c-4e8a-9f17-2c5b8d1e4a60" },
  "initiated_by_you": true,
  "cancellable": false,
  "created_at": "2026-11-12T10:00:20Z",
  "updated_at": "2026-11-12T10:00:20Z"
}

The new Payout's state is one of:

  • processing: your balance covered it, the amount is held, and the route is running.
  • awaiting_approval: your approval rules hold it for a second person, who approves it in the Customer panel. An API key never approves.
  • accepted: your balance at the route's first Provider does not cover it yet. It waits for funds and is cancelled if its Quote expires first, so fund your balance before you send.

A Quote turns into one Payout only. Accepting it again with a different Idempotency-Key answers quote_already_used (409). Until a Payout is funded (accepted or awaiting_approval) you can cancel it with POST /v1/payouts/{id}/cancel.

Follow it to the end

By webhook (recommended). Register an endpoint for payout.updated and we send you the full Payout on every state change. See Webhooks.

By polling. Read the Payout until it reaches a final state. Poll every few seconds at most and back off over time.

curl "$APEX_BASE_URL/v1/payouts/7d41f0b2-9c3e-4a85-b6d1-2e8f5a7c9b13" \
  -H "Authorization: Bearer $APEX_API_KEY"
200 OK (trimmed)
{
  "id": "7d41f0b2-9c3e-4a85-b6d1-2e8f5a7c9b13",
  "state": "completed",
  "receive": { "amount": "918.58", "asset": "EUR" },
  "legs": [
    { "index": 0, "provider": "bvnk", "from": "USDC", "to": "EUR", "state": "completed", "settled_at": "2026-11-12T10:01:04Z" },
    { "index": 1, "provider": "bvnk", "from": "EUR", "to": "EUR", "state": "completed", "settled_at": "2026-11-12T10:02:11Z" }
  ],
  "timeline": [
    { "state": "accepted", "at": "2026-11-12T10:00:20Z", "by": { "actor": "customer", "kind": "api_key", "id": "a3d9e1f4-6b2c-4e8a-9f17-2c5b8d1e4a60" } },
    { "state": "funded", "at": "2026-11-12T10:00:20Z", "by": { "actor": "customer", "kind": "api_key", "id": "a3d9e1f4-6b2c-4e8a-9f17-2c5b8d1e4a60" } },
    { "state": "processing", "at": "2026-11-12T10:00:20Z", "by": { "actor": "customer", "kind": "api_key", "id": "a3d9e1f4-6b2c-4e8a-9f17-2c5b8d1e4a60" } },
    { "state": "completed", "at": "2026-11-12T10:02:11Z", "by": { "actor": "system" } }
  ]
}

completed, refunded and cancelled are final. failed is not: our operations team either retries the failed Leg, which takes the Payout back to processing, or refunds it to your balance (refunded). A failed Payout carries failure, which names the Leg that failed and a code.

Next steps

On this page