İçeriğe geç
Apex Settlement
Beneficiaries

Register a Beneficiary

Gereken izincustomer:beneficiaries:writeAPI referansındaki uç nokta açıklamaları İngilizcedir.
POST
/v1/beneficiaries

Registers a party the Customer will pay: external (an outside person or business) or own_account (the Customer's own account elsewhere, which needs proof_reference, a reference to the evidence that the account is the Customer's). details holds the account fields the Rails to its country and asset ask for, such as iban for a SEPA payout, or account_number and bank_code; a key no such Rail asks for is refused.

The Beneficiary starts pending_verification; the operations team verifies it, and the beneficiary.updated webhook says when it can be quoted and paid. To pay another Customer of the platform, add it with POST /v1/beneficiaries/link instead.

Requires the customer:beneficiaries:write permission. A Platform may call it for one of its End Customers with Apex-End-Customer.

Yetkilendirme

ApiKey
headerYetkilendirmeBearer <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.

Başlık parametreleri

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.

Biçimuuid

İstek gövdesi

The party and its account.

application/json
  1. body
asset*string

asset is what the Beneficiary is paid in.

Uzunluklength <= 10
country*string

country is where the Beneficiary is paid, two letters (ISO 3166-1).

details?

details are the account fields the Rails to that country and asset ask for.

kind*BeneficiaryKind
Değerin yeri"external""own_account"
name*string
Uzunluklength <= 256
party_type*PartyType
Değerin yeri"individual""business"
proof_reference?string

proof_reference points at the evidence that an own_account is the Customer's; required for one.

Uzunluklength <= 256

Yanıt gövdesi

Created

application/json
  1. response
account_hint?string

account_hint is the last four characters of the account paid.

asset*string

asset is what the Beneficiary is paid in.

available*boolean

available is false for a Beneficiary that is another Customer which cannot be paid now (neither a Receiving Account nor a balance it can be credited in, or it may not receive); it keeps its state, and a Payout to it is refused while it lasts.

country*string
created_at*string
Biçimdate-time
delivers_to?string

delivers_to is, for another Customer, where a Payout to it would end now: balance (its balance on the platform; account_hint is then empty when it has no Receiving Account) or bank_account. Absent for other kinds and while it is unavailable.

Değerin yeri"balance""bank_account"
details*

details are the account fields, as registered; empty for another Customer.

id*string
kind*string

kind is external (an outside party), own_account (the Customer's own account elsewhere) or customer (another Customer, added by its Receiving Code).

Değerin yeri"external""own_account""customer"
name*string
party_type*string
Değerin yeri"individual""business"
state*string
Değerin yeri"pending_verification""verified""blocked"
updated_at*string
Biçimdate-time
verified_at?string
Biçimdate-time
Örnek istek
curl -X POST 'http://localhost:3480/v1/beneficiaries' \  -H 'Content-Type: application/json' \  -d '{  "asset": "EUR",  "country": "DE",  "kind": "external",  "name": "Berlin Supplies GmbH",  "party_type": "business"}'
Örnek yanıt
{  "account_hint": "3000",  "asset": "EUR",  "available": true,  "country": "DE",  "created_at": "2026-11-12T08:02:11Z",  "delivers_to": "balance",  "details": {    "iban": "DE89370400440532013000",    "name": "Berlin Supplies GmbH"  },  "id": "7a1e4c2b-9d3f-4e8a-b6c5-1f2e3d4c5b6a",  "kind": "external",  "name": "Berlin Supplies GmbH",  "party_type": "business",  "state": "verified",  "updated_at": "2026-11-12T08:15:00Z",  "verified_at": "2026-11-12T08:15:00Z"}