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
kind | Who it is | How you add it |
|---|---|---|
external | A third party: a company or a person you pay. | POST /v1/beneficiaries |
own_account | Your 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 |
customer | Another 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"
}
}'{
"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:
| Destination | details keys |
|---|---|
| EUR in a SEPA country: the 27 EU members, Iceland, Liechtenstein, Norway, Switzerland, the United Kingdom, Monaco, San Marino, Vatican City and Andorra | iban, 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 account | account_number, bank_code |
| PKR in Pakistan (PK), mobile wallet | wallet_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 indetails[].field, asdetails.<key>. - An
ibanmust pass the IBAN checksum, or the call answersiban_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
processinglonger. Send every key of your destination.
Verification
state | Meaning |
|---|---|
pending_verification | Registered, not payable yet. Quotes to it answer beneficiary_not_verified. |
verified | Payable. |
blocked | Our 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.
Link another Customer with a Receiving Code
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" }'{
"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
200with the Beneficiary you already have. It never creates a second one. detailsis always empty for acustomerBeneficiary.account_hintis 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.countryandassetfollow 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 withbeneficiary_changed: quote again.- A new code replaces the old one for new senders only. A Beneficiary you already linked keeps working.
| Code | Status | Cause |
|---|---|---|
receiving_code_not_found | 404 | The code is unknown, or that Customer cannot receive payments now. The answer is the same for both. |
cannot_link_self | 422 | It is your own code. |
receiving_account_missing | 409 | That 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_to | Meaning |
|---|---|
bank_account | The receiving Customer's bank account. |
balance | The 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
| Code | Status | Cause |
|---|---|---|
validation_failed | 400 | A required field is missing or too long, kind is not external or own_account, or details has more than 20 keys. |
beneficiary_fields_invalid | 422 | A key in details is not asked for by any route to that country and asset. |
iban_invalid | 422 | The IBAN fails its checksum. |
proof_required | 422 | An own_account without proof_reference. |
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. |