Skip to Content
Apex Settlement

Beneficiaries

Register the people and companies you pay, give each destination the details it needs, and link other Customers by their Receiving Code.

A Beneficiary is whoever receives a Payout. You register it once, it is verified, and from then on you quote and pay it by its id. Its country and asset decide where your money goes: you never send a destination with a quote.

Kinds of Beneficiary

kindWho it isHow you add it
externalA third party: a company or a person you pay.POST /v1/beneficiaries
own_accountYour own account, such as your company's account at another bank. You pay it to withdraw your balance, and you can make it your Receiving Account.POST /v1/beneficiaries, with a proof of ownership
customerAnother Customer of the platform. You pay into the account it chose; you never see or type its details.POST /v1/beneficiaries/link, with its Receiving Code

A company in your group that is a separate legal entity is an external Beneficiary, not an own_account.

Register a Beneficiary

POST /v1/beneficiaries needs an API key with customer:beneficiaries:write.

Prop

Type

Tom pays a supplier in the United Kingdom:

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": "Northwind Supplies Ltd",
    "country": "GB",
    "asset": "GBP",
    "details": {
      "account_number": "31926819",
      "sort_code": "601613",
      "name": "Northwind Supplies Ltd"
    }
  }'
201 Created
{
  "id": "6f1c2a9e-3b7d-4c58-9a21-0d4e8b7f5c13",
  "kind": "external",
  "state": "pending_verification",
  "party_type": "business",
  "name": "Northwind Supplies Ltd",
  "country": "GB",
  "asset": "GBP",
  "details": {
    "account_number": "••••6819",
    "sort_code": "601613",
    "name": "Northwind Supplies Ltd"
  },
  "available": true,
  "created_at": "2026-11-12T09:30:00Z",
  "updated_at": "2026-11-12T09:30:00Z"
}

Account-like values come back masked: any detail whose key contains iban, account, number, wallet or address shows •••• and its last four characters. Keep the full values in your own system if you need them.

Details for each destination

The keys in details are the ones the routes to that country and asset ask for:

Destinationdetails keys
EUR in a SEPA country: the 27 EU members, Iceland, Liechtenstein, Norway, Switzerland, the United Kingdom, Monaco, San Marino, Vatican City and Andorraiban, name
GBP in the United Kingdom (GB)account_number, sort_code, name
USD in the United States (US)account_number, routing_number, name
PKR in Pakistan (PK), bank accountaccount_number, bank_code
PKR in Pakistan (PK), mobile walletwallet_phone, wallet_type

name is the account holder's name as the bank knows it.

{
  "kind": "external",
  "party_type": "business",
  "name": "Kranich Logistik GmbH",
  "country": "DE",
  "asset": "EUR",
  "details": {
    "iban": "DE89370400440532013000",
    "name": "Kranich Logistik GmbH"
  }
}

What the registration checks:

  • A key no route to that country and asset asks for is refused with beneficiary_fields_invalid. Each refused key is named in details[].field, as details.<key>.
  • An iban must pass the IBAN checksum, or the call answers iban_invalid.
  • A missing key is not refused at registration. But a route that needs a key you left out sends the Payout to a manual review, and it stays processing longer. Send every key of your destination.

Verification

stateMeaning
pending_verificationRegistered, not payable yet. Quotes to it answer beneficiary_not_verified.
verifiedPayable.
blockedOur compliance team stopped it. It can no longer be paid, and the state is final.

Every Beneficiary you register through the API starts as pending_verification. Our compliance team reviews it, which includes screening the party against sanctions and politically-exposed-persons lists, then verifies or blocks it. You see only the state, never the screening itself. An own_account is verified only after compliance has checked its proof_reference.

A verified Beneficiary can still be blocked later. A Payout already on its way finishes; new quotes to it are refused.

Subscribe to the beneficiary.updated webhook to learn when the state changes, rather than polling. See Webhooks.

Register Beneficiaries ahead of the payments you plan, so the review is done by the time you need to pay.

Another Customer of the platform gives you its Receiving Code, a short code such as RC-7KQ2-M9XD. Entering it adds that Customer as a Beneficiary of kind customer, verified at once. You pay into the account it chose, and its details stay with it.

curl -X POST "$APEX_BASE_URL/v1/beneficiaries/link" \
  -H "Authorization: Bearer $APEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "receiving_code": "RC-7KQ2-M9XD" }'
201 Created
{
  "id": "c4e7a2d9-1b3f-4a68-9e05-7d2c8b6f1a34",
  "kind": "customer",
  "state": "verified",
  "party_type": "business",
  "name": "Lina Textiles Ltd",
  "country": "PK",
  "asset": "PKR",
  "details": {},
  "account_hint": "6789",
  "available": true,
  "delivers_to": "bank_account",
  "verified_at": "2026-11-12T09:40:00Z",
  "created_at": "2026-11-12T09:40:00Z",
  "updated_at": "2026-11-12T09:40:00Z"
}
  • The code is read in any case, with or without dashes.
  • Linking the same Customer again answers 200 with the Beneficiary you already have. It never creates a second one.
  • details is always empty for a customer Beneficiary. account_hint is the last four characters of the account it receives into, and is absent when the money goes to its platform balance and it has no account.
  • country and asset follow the receiving Customer. If it chooses another account later, your next quote pays the new one. A quote you took before the change is refused at acceptance with beneficiary_changed: quote again.
  • A new code replaces the old one for new senders only. A Beneficiary you already linked keeps working.
CodeStatusCause
receiving_code_not_found404The code is unknown, or that Customer cannot receive payments now. The answer is the same for both.
cannot_link_self422It is your own code.
receiving_account_missing409That Customer has not chosen where it receives yet. Ask it to set a Receiving Account.

To receive payments the same way, see Receiving payouts.

available and delivers_to

Every Beneficiary carries available. It is false only for a customer Beneficiary that cannot be paid right now: that Customer has nowhere to receive the money, or its account with us is not active. It keeps its state while that lasts. Quotes to it answer beneficiary_not_verified and a Payout to it is refused with beneficiary_unavailable, until it is available again.

A customer Beneficiary also carries delivers_to, where a Payout to it would end now:

delivers_toMeaning
bank_accountThe receiving Customer's bank account.
balanceThe receiving Customer's platform balance, in its own country.

delivers_to is absent for other kinds and while the Beneficiary is not available.

Read your Beneficiaries

GET /v1/beneficiaries answers all of them as a list. GET /v1/beneficiaries/{id} answers one. Both need customer:read. Another Customer's id answers beneficiary_not_found.

Errors

CodeStatusCause
validation_failed400A required field is missing or too long, kind is not external or own_account, or details has more than 20 keys.
beneficiary_fields_invalid422A key in details is not asked for by any route to that country and asset.
iban_invalid422The IBAN fails its checksum.
proof_required422An own_account without proof_reference.
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.

Next steps

On this page