Platformlar
Kendi müşterilerinize End Customer olarak hizmet verin, onları API ile açıp doğrulayın ve tek bir başlıkla her biri adına işlem yapın.
Platform, kendi müşterileri adına ödeme gönderen kurumsal bir müşteridir. Bu müşterilerin her biri bir End Customer'dır: sözleşmesi sizinledir, ancak yönlendirildiği her Provider'da due diligence'tan geçer ve kendi bakiyesini tutar. Sisteminiz End Customer'ları açar, doğrulamalarını yürütür ve paralarını hareket ettirir; hepsini kendi API anahtarlarınızla.
Platform olmak
Aktif bir kurumsal hesap, biz açtığımızda Platform olur; hesap yöneticinizle görüşün. Bundan sonra GET /v1/customer yanıtı "kind": "platform" olur. Doğrudan bir müşteri direct, bir End Customer ise end_customer okur.
API anahtarlarınıza burada önemli olan iki izin verilebilir:
| İzin | Ne sağlar |
|---|---|
customer:end_customers:manage | End Customer açma, askıya alma ve yeniden açma. |
customer:profile:write | Bir End Customer'ın doğrulamasını yürütme: profil, belgeler, koşullar ve gönderim. |
End Customer'ları okumak customer:read ister.
End Customer açma
POST /v1/end-customers bir End Customer açar. POST /v1/payouts gibi Idempotency-Key ister. Bkz. Idempotency.
Alan
Tür
curl -X POST "$APEX_BASE_URL/v1/end-customers" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"type": "business",
"legal_name": "Harbor Crafts LLC",
"email": "ops@harborcrafts.example.com",
"country": "US"
}'{
"id": "a1f3c5e7-2b4d-4f68-8a9c-0e1d2c3b4a59",
"type": "business",
"legal_name": "Harbor Crafts LLC",
"email": "ops@harborcrafts.example.com",
"country": "US",
"state": "profile_pending",
"standing": "onboarding",
"providers": [],
"created_at": "2026-11-12T09:00:00Z",
"updated_at": "2026-11-12T09:00:00Z"
}invite_email olmadan her adımı sisteminiz API ile yapar. Verildiğinde, End Customer'dan bir kişi müşteri paneline de giriş yapabilir ve yalnızca kendi hesabını görür. İki yol yan yana çalışır.
Kişi davet etmek bir kişi ister
invite_email ve POST /v1/end-customers/{id}/invite, bir API anahtarıyla gönderildiğinde people_only (403) ile reddedilir. Daveti Platformunuzdan bir kişi müşteri panelinden gönderir. Bir End Customer bir kez davet edilebilir: içinde bir kişi olduktan sonra davet end_customer_has_people (409) döner ve diğerlerini kendi kişileri davet eder.
Listeleme, okuma, askıya alma
| Çağrı | Ne yapar |
|---|---|
GET /v1/end-customers | End Customer'larınız, en yenisi önce. Filtreler: state, q (yasal adın ya da e-postanın bir kısmı), limit (varsayılan 50, en fazla 500) ve offset. |
GET /v1/end-customers/{id} | Tek bir End Customer; providers (her Provider'daki başvurusu: submitted, info_required, approved, rejected ya da terminated) ve has_people ile. |
POST /v1/end-customers/{id}/suspend | Bir reason ile durdurur. End Customer salt okunur olur; yoldaki ödemeler tamamlanır. |
POST /v1/end-customers/{id}/reactivate | Sizin yaptığınız bir askıya almayı kaldırır. |
suspended_by kimin askıya aldığını söyler: platform (siz) ya da operator (uyum ekibimiz). Yalnızca kendi askıya almanızı kaldırabilirsiniz; bizimki suspended_by_operator (403) döner. suspended_reason yalnızca sizin askıya almanız için gösterilir.
Hesabı Platform olmayan bir çağıran bu çağrılarda not_a_platform (403) alır. Bu çağrıları Apex-End-Customer başlığı olmadan gönderin: bir End Customer üzerinde değil, Platformunuz üzerinde çalışırlar.
Bir End Customer adına işlem yapma
Diğer herhangi bir /v1 çağrısına End Customer'ın id değeriyle Apex-End-Customer başlığını ekleyin. Çağrı, tam olarak End Customer yapmış gibi çalışır: onun bakiyeleri, alıcıları, teklifleri ve ödemeleri. Anahtarınızın izinleri aynı kalır.
curl "$APEX_BASE_URL/v1/balances" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Apex-End-Customer: a1f3c5e7-2b4d-4f68-8a9c-0e1d2c3b4a59"| Endpoint'ler | Başlıkla |
|---|---|
/v1/customer, /v1/balances, /v1/deposit-instructions, /v1/beneficiaries*, /v1/quotes, /v1/payouts*, /v1/receiving*, /v1/incoming-payouts*, /v1/onboarding, /v1/profile*, /v1/documents*, /v1/terms | End Customer için çalışır. |
/v1/webhooks*, /v1/api-keys* | not_for_end_customers (403) ile reddedilir. Webhook uç noktaları ve anahtarlar Platform'a aittir. |
/v1/team* | not_while_acting (403) ile reddedilir. |
/v1/end-customers* | Reddedilir: Platform üzerinde çalışırlar. Başlıksız gönderin. |
/v1/auth/*, /v1/signup/* | Başlık yok sayılır. |
Başlık, End Customer'larınızdan biri olmayan bir kimliği adlandırırsa ya da hesabınız Platform değilse çağrı end_customer_not_found (404) döner. Yanıt, böyle bir müşterinin var olup olmadığını hiçbir zaman söylemez.
End Customer'ın kendi durumu geçerlidir: doğrulama sürerken onun için yalnızca doğrulama endpoint'leri çalışır (bkz. Doğrulama); askıdayken yalnızca okuyabilir. Platformunuz askıdaysa her End Customer da salt okunurdur.
Idempotency-Key değerleri End Customer başına tutulur: aynı anahtar iki farklı End Customer için gönderildiğinde iki ayrı kayıt oluşturur.
Bir End Customer'ı doğrulama
Bir End Customer, her müşterinin geçtiği KYC ya da KYB'den aynı çağrılarla, kendi başlığıyla geçer. Bkz. Doğrulama. Farklar:
- Yalnızca gönderileceği Provider'ların koşullarını kabul eder.
GET /v1/termsbunları listeler. - Bizimle bir sözleşme adımı yoktur: yolu
profile_pending,profile_review,provider_onboarding, sonraactiveşeklindedir. - Uyum ekibimiz profilini onayladığında, Platformunuzu onaylamış her Provider'a otomatik olarak gönderilir.
- Bu Provider'lardan ilki onu onayladığı anda
activeolur.
Bir End Customer'ın doğrulaması için webhook yoktur. İzlemek için GET /v1/end-customers/{id} (state ve providers) ya da onun başlığıyla GET /v1/onboarding okuyun.
Para
Her End Customer'ın kendi bakiyeleri, kendi para yatırma talimatları, kendi alıcıları ve kendi ödemeleri vardır. Platformunuzun bakiyesiyle bir End Customer'ınki arasında hiçbir şey taşınmaz. Bir End Customer'ı fonlamak için, onun başlığıyla GET /v1/deposit-instructions çağrısının döndüğü talimatlarla para yatırın.
Bir End Customer'ın teklifleri, onun için anlaşılan ücretleri taşır; ayrıca anlaşılmadıysa Platform'unkileri.
Onaylar
Bir End Customer'ın kendi onay kuralları varsa onlar, yoksa Platformunuzunkiler geçerlidir. Bir End Customer'ın bekleyen ödemesini, End Customer'dan ya da Platformunuzdan onaylama iznine sahip herhangi bir kişi müşteri panelinde onaylayabilir. Her ödemede olduğu gibi, ödemeyi başlatan kişi onaylayamaz ve API anahtarları asla onaylamaz. Bkz. Ödeme gönderme.
Webhook'lar
Platformunuzun webhook uç noktaları tüm End Customer'larınızın olaylarını alır. Böyle bir olay, zarfın en üst düzeyinde end_customer_id taşır:
{
"id": "1b6c9e2f-7a3d-5c48-8e1f-2d4a6b8c0e13",
"type": "payout.updated",
"created_at": "2026-11-12T10:02:05Z",
"end_customer_id": "a1f3c5e7-2b4d-4f68-8a9c-0e1d2c3b4a59",
"data": { "id": "f0e1d2c3-b4a5-4968-8776-655443322110", "state": "completed" }
}data kaynağın tamamıdır; burada kısaltıldı. Platformunuzun kendisiyle ilgili bir olayda end_customer_id yoktur. Bkz. Webhook'lar.
Hatalar
| Kod | Durum | Nedeni |
|---|---|---|
not_a_platform | 403 | Hesabınız Platform değil ya da bir /v1/end-customers çağrısına Apex-End-Customer gönderdiniz. |
end_customer_not_found | 404 | Kimlik, End Customer'larınızdan birine ait değil. |
not_for_end_customers | 403 | Webhook'lar ve API anahtarları bir End Customer için reddedilir. |
not_while_acting | 403 | Bir End Customer adına işlem yaparken ekip endpoint'leri reddedilir. |
people_only | 403 | Bir davet API anahtarıyla gönderildi. |
end_customer_has_people | 409 | End Customer'da zaten kişiler var; diğerlerini onlar davet eder. |
suspended_by_operator | 403 | Bu End Customer'ı biz askıya aldık; yalnızca biz kaldırabiliriz. |
country_not_accepted | 422 | Bu ülkeden müşteri kabul etmiyoruz. |
customer_suspended | 403 | End Customer ya da Platformunuz askıda: yalnızca okuma. |
customer_not_active | 403 | End Customer hâlâ doğrulamada ya da reddedildi. |