Skip to Content
Apex Settlement
Payouts

Accept a Quote into a Payout

Required permissioncustomer:payouts:create
POST
/v1/payouts

Accepts one Quote of a quote set, named by its quote_id, before its expires_at. The answer is the new Payout, in one of these states:

  • awaiting_approval: the Customer's approval rules hold it until a second person of the Customer approves it in the Customer panel;
  • accepted: the balance at the Provider its Route starts at does not cover the send amount yet; the next Deposit there funds it, and it is cancelled if the Quote ends first (money held at another Provider is never combined);
  • funded or processing: the money was there and the Payout is on its way.

Follow it with GET /v1/payouts/{id} or the payout.updated webhook. One quote_id makes one Payout. When an answer is lost or is a 5xx, retry with the same Idempotency-Key; if the retry answers quote_already_used, the Payout exists: find it with GET /v1/payouts.

Requires the customer:payouts:create permission. Send an Idempotency-Key: a retry with the same key and body answers the first response again (marked Idempotency-Replayed: true) for 24 hours. A Platform may call it for one of its End Customers with Apex-End-Customer.

Authorization

ApiKey
headerAuthorizationBearer <API key>

A Customer API key, created by a Customer admin in the Customer panel and shown once: Authorization: Bearer ak_live_… in production, ak_test_… elsewhere. A key holds a subset of its creator's permissions and may be limited to named IP addresses and an expiry date. Keys never manage people, other keys or approval rules, and never approve a Payout.

Header Parameters

Apex-End-Customer?string

A Platform acting for one of its End Customers names it here: the request then reads and changes that End Customer's resources, under the API key's own permissions. Leave it out to act for the Platform itself. An id that is not one of the caller's End Customers answers end_customer_not_found.

Formatuuid
Idempotency-Key*string

A unique key per intended request, such as a UUID. A retry with the same key and body answers the first response again for 24 hours instead of acting twice; the same key with another body is idempotency_key_reused. An error answer is not kept, so a request that failed may be retried under its key.

Lengthlength <= 128

Request Body

The Quote to accept.

application/json
  1. body
quote_id*string

quote_id is the quote_id of the Quote to accept.

Lengthlength <= 4096

Response Body

Created

application/json
  1. response
beneficiary*
cancellable*boolean

cancellable says whether POST /v1/payouts/{id}/cancel would succeed now.

created_at*string
Formatdate-time
delivered_to*string

delivered_to is where the Payout ends: balance (the receiving Customer's platform balance) or bank_account.

Value in"balance""bank_account"
failure?
fees*array<>
id*string
initiated_by*
initiated_by_you?boolean

initiated_by_you says whether the caller started the Payout, in person or through a key the caller created (or, for a key, the person who created it). Every /v1 answer sets it; a webhook, which has no caller, leaves it out.

legs*array<>
rates*array<>
receive*
send*
state*string
Value in"awaiting_approval""accepted""funded""processing""completed""failed""refunded""cancelled"
updated_at*string
Formatdate-time
Example Request
curl -X POST 'http://localhost:3480/v1/payouts' \  -H 'Idempotency-Key: 5f1c2b9e-6a1d-4c3e-9b7a-2d8e4f6a1c03' \  -H 'Content-Type: application/json' \  -d '{  "quote_id": "qt1.eyJkZWNpc2lvbl9pZCI6IjRmOWU4ZDdjIn0.k3Jv9zQh1sX0pL2mN8bR4tY6uW5aE7cD"}'
Example Response
{  "beneficiary": {    "country": "DE",    "id": "7a1e4c2b-9d3f-4e8a-b6c5-1f2e3d4c5b6a",    "name": "Berlin Supplies GmbH",    "party_type": "business"  },  "cancellable": false,  "created_at": "2026-11-12T09:30:02Z",  "delivered_to": "bank_account",  "failure": null,  "fees": [    {      "amount": {        "amount": "1",        "asset": "USDC"      },      "component": "provider",      "provider": "bvnk"    },    {      "amount": {        "amount": "0.5",        "asset": "EUR"      },      "component": "provider",      "provider": "bvnk"    }  ],  "id": "5f8d0c3e-2b7a-4d1e-9c6f-8a3b2e1d0c9f",  "initiated_by": {    "actor": "customer",    "id": "6e5d4c3b-2a1f-4e0d-8c9b-7a6f5e4d3c2b",    "kind": "api_key"  },  "initiated_by_you": true,  "legs": [    {      "from": "USDC",      "index": 0,      "provider": "bvnk",      "settled_at": "2026-11-12T09:30:41Z",      "state": "completed",      "to": "EUR"    },    {      "from": "EUR",      "index": 1,      "provider": "bvnk",      "settled_at": "2026-11-12T09:31:05Z",      "state": "completed",      "to": "EUR"    }  ],  "rates": [    {      "provider": "bvnk",      "rate": "0.92"    }  ],  "receive": {    "amount": "918.58",    "asset": "EUR"  },  "send": {    "amount": "1000",    "asset": "USDC"  },  "state": "completed",  "updated_at": "2026-11-12T09:31:05Z"}