Alıcılar
Ödeme yaptığınız kişi ve şirketleri kaydedin, her hedefin istediği bilgileri verin ve diğer müşterileri Alım Koduyla ekleyin.
Alıcı, bir ödemeyi alan taraftır. Onu bir kez kaydedersiniz, doğrulanır ve sonrasında id değeriyle teklif alıp ödeme yaparsınız. Paranızın nereye gideceğini alıcının ülkesi ve para birimi belirler: teklif isterken hiçbir zaman hedef göndermezsiniz.
Alıcı türleri
kind | Kim | Nasıl eklenir |
|---|---|---|
external | Dış alıcı: ödeme yaptığınız bir şirket ya da kişi. | POST /v1/beneficiaries |
own_account | Kendi hesabınız; örneğin şirketinizin başka bir bankadaki hesabı. Bakiyenizi bankanıza çekmek için ona ödeme yaparsınız ve onu Alım Hesabınız yapabilirsiniz. | POST /v1/beneficiaries, sahiplik belgesiyle |
customer | Platformdaki başka bir müşteri. Onun seçtiği hesaba ödersiniz; hesap bilgilerini hiçbir zaman görmez ve yazmazsınız. | POST /v1/beneficiaries/link, Alım Koduyla |
Grubunuzda ayrı bir tüzel kişi olan bir şirket external alıcıdır, own_account değildir.
Alıcı kaydetme
POST /v1/beneficiaries, customer:beneficiaries:write iznine sahip bir API anahtarı ister.
Alan
Tür
Tom, Birleşik Krallık'taki bir tedarikçisine ödeme yapıyor:
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"
}Hesap numarası benzeri değerler maskeli döner: anahtarında iban, account, number, wallet ya da address geçen her alan •••• ve son dört karakteriyle gösterilir. Tam değerlere ihtiyacınız varsa kendi sisteminizde saklayın.
Her hedef için hesap bilgileri
details anahtarları, o ülke ve para birimine giden rotaların istedikleridir:
| Hedef | details anahtarları |
|---|---|
| Bir SEPA ülkesinde EUR: 27 AB üyesi, İzlanda, Lihtenştayn, Norveç, İsviçre, Birleşik Krallık, Monako, San Marino, Vatikan ve Andorra | iban, name |
| Birleşik Krallık'ta (GB) GBP | account_number, sort_code, name |
| ABD'de (US) USD | account_number, routing_number, name |
| Pakistan'da (PK) PKR, banka hesabı | account_number, bank_code |
| Pakistan'da (PK) PKR, mobil cüzdan | wallet_phone, wallet_type |
name, bankanın bildiği hesap sahibi adıdır.
{
"kind": "external",
"party_type": "business",
"name": "Kranich Logistik GmbH",
"country": "DE",
"asset": "EUR",
"details": {
"iban": "DE89370400440532013000",
"name": "Kranich Logistik GmbH"
}
}Kayıt sırasında şunlar kontrol edilir:
- O ülke ve para birimine giden hiçbir rotanın istemediği bir anahtar
beneficiary_fields_invalidile reddedilir. Reddedilen her anahtardetails[].fieldiçindedetails.<anahtar>olarak adlandırılır. ibandeğeri IBAN kontrol hanesinden geçmelidir; geçmezse yanıtiban_invalidolur.- Eksik bir anahtar kayıtta reddedilmez. Ancak bıraktığınız bir anahtarı isteyen bir rota, ödemeyi elle incelemeye gönderir ve ödeme daha uzun süre
processingdurumunda kalır. Hedefinizin her anahtarını gönderin.
Doğrulama
state | Anlamı |
|---|---|
pending_verification | Doğrulanıyor: kaydedildi, henüz ödenemez. Ona teklif istendiğinde yanıt beneficiary_not_verified olur. |
verified | Doğrulandı: ödenebilir. |
blocked | Engellendi: uyum ekibimiz durdurdu. Artık ödenemez ve bu durum kalıcıdır. |
API ile kaydettiğiniz her alıcı pending_verification olarak başlar. Uyum ekibimiz onu inceler; buna tarafın yaptırım ve siyasi nüfuz sahibi kişi (PEP) listelerinde taranması da dahildir. Ardından doğrular ya da engeller. Siz yalnızca durumu görürsünüz, taramanın kendisini görmezsiniz. Bir own_account, ancak uyum ekibi proof_reference değerini kontrol ettikten sonra doğrulanır.
Doğrulanmış bir alıcı daha sonra da engellenebilir. Yolda olan bir ödeme tamamlanır; yeni teklifler reddedilir.
Durumun ne zaman değiştiğini sorgulayarak değil, beneficiary.updated webhook'una abone olarak öğrenin. Bkz. Webhook'lar.
Alıcıları planladığınız ödemelerden önce kaydedin; ödeme yapmanız gerektiğinde inceleme tamamlanmış olur.
Başka bir müşteriyi Alım Koduyla ekleme
Platformdaki başka bir müşteri size Alım Kodunu verir; RC-7KQ2-M9XD gibi kısa bir kod. Bu kodu girdiğinizde o müşteri customer türünde bir alıcı olarak eklenir ve hemen verified olur. Onun seçtiği hesaba ödersiniz; hesap bilgileri onda kalır.
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"
}- Kod büyük-küçük harf fark etmeksizin, tireli ya da tiresiz okunur.
- Aynı müşteriyi yeniden eklemek, elinizdeki alıcıyla
200döner. Hiçbir zaman ikinci bir alıcı oluşturmaz. customertüründeki bir alıcınındetailsalanı her zaman boştur.account_hint, paranın yatırılacağı hesabın son dört karakteridir; para müşterinin platform bakiyesine gidiyorsa ve hesabı yoksa gelmez.countryveasset, alıcı müşteriyi izler. Müşteri daha sonra başka bir hesap seçerse bir sonraki teklifiniz yeni hesaba öder. Değişiklikten önce aldığınız bir teklif kabuldebeneficiary_changedile reddedilir: yeniden teklif isteyin.- Yeni bir kod eskisinin yerini yalnızca yeni gönderenler için alır. Daha önce eklediğiniz alıcı çalışmaya devam eder.
| Kod | Durum | Nedeni |
|---|---|---|
receiving_code_not_found | 404 | Kod bilinmiyor ya da o müşteri şu an ödeme alamıyor. Yanıt ikisi için de aynıdır. |
cannot_link_self | 422 | Kendi kodunuz. |
receiving_account_missing | 409 | O müşteri parayı nereye alacağını henüz seçmedi. Bir Alım Hesabı seçmesini isteyin. |
Aynı şekilde ödeme almak için bkz. Ödeme alma.
available ve delivers_to
Her alıcı available alanını taşır. Bu alan yalnızca şu an ödenemeyen customer türündeki bir alıcı için false olur: o müşterinin parayı alacağı bir yer yoktur ya da bizdeki hesabı aktif değildir. Bu sürerken state değeri korunur. Ona teklif istendiğinde yanıt beneficiary_not_verified olur, ona yapılan ödeme ise tekrar ödenebilir olana kadar beneficiary_unavailable ile reddedilir.
customer türündeki bir alıcı ayrıca delivers_to taşır; ona yapılacak bir ödemenin şu an nerede biteceğini söyler:
delivers_to | Anlamı |
|---|---|
bank_account | Alıcı müşterinin banka hesabı. |
balance | Alıcı müşterinin kendi ülkesindeki platform bakiyesi. |
Diğer türlerde ve alıcı ödenemez durumdayken delivers_to gelmez.
Alıcılarınızı okuma
GET /v1/beneficiaries hepsini bir liste olarak döner. GET /v1/beneficiaries/{id} tek bir alıcıyı döner. İkisi de customer:read ister. Başka bir müşterinin kimliği beneficiary_not_found döner.
Hatalar
| Kod | Durum | Nedeni |
|---|---|---|
validation_failed | 400 | Zorunlu bir alan eksik ya da çok uzun, kind değeri external ya da own_account değil, veya details 20'den fazla anahtar taşıyor. |
beneficiary_fields_invalid | 422 | details içindeki bir anahtarı o ülke ve para birimine giden hiçbir rota istemiyor. |
iban_invalid | 422 | IBAN kontrol hanesinden geçmiyor. |
proof_required | 422 | proof_reference olmadan bir own_account. |
beneficiary_not_found | 404 | Bu kimlikle size ait bir alıcı yok. |
customer_suspended | 403 | Hesabınız askıda; yalnızca okuyabilir. |
customer_not_active | 403 | Hesabınız henüz açılmadı ya da kapalı. |