İçeriğe geç
Apex Settlement

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

kindKimNasıl eklenir
externalDış alıcı: ödeme yaptığınız bir şirket ya da kişi.POST /v1/beneficiaries
own_accountKendi 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
customerPlatformdaki 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"
    }
  }'
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"
}

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:

Hedefdetails anahtarları
Bir SEPA ülkesinde EUR: 27 AB üyesi, İzlanda, Lihtenştayn, Norveç, İsviçre, Birleşik Krallık, Monako, San Marino, Vatikan ve Andorraiban, name
Birleşik Krallık'ta (GB) GBPaccount_number, sort_code, name
ABD'de (US) USDaccount_number, routing_number, name
Pakistan'da (PK) PKR, banka hesabıaccount_number, bank_code
Pakistan'da (PK) PKR, mobil cüzdanwallet_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_invalid ile reddedilir. Reddedilen her anahtar details[].field içinde details.<anahtar> olarak adlandırılır.
  • iban değeri IBAN kontrol hanesinden geçmelidir; geçmezse yanıt iban_invalid olur.
  • 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 processing durumunda kalır. Hedefinizin her anahtarını gönderin.

Doğrulama

stateAnlamı
pending_verificationDoğrulanıyor: kaydedildi, henüz ödenemez. Ona teklif istendiğinde yanıt beneficiary_not_verified olur.
verifiedDoğrulandı: ödenebilir.
blockedEngellendi: 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" }'
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"
}
  • Kod büyük-küçük harf fark etmeksizin, tireli ya da tiresiz okunur.
  • Aynı müşteriyi yeniden eklemek, elinizdeki alıcıyla 200 döner. Hiçbir zaman ikinci bir alıcı oluşturmaz.
  • customer türündeki bir alıcının details alanı 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.
  • country ve asset, 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 kabulde beneficiary_changed ile 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.
KodDurumNedeni
receiving_code_not_found404Kod bilinmiyor ya da o müşteri şu an ödeme alamıyor. Yanıt ikisi için de aynıdır.
cannot_link_self422Kendi kodunuz.
receiving_account_missing409O 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_toAnlamı
bank_accountAlıcı müşterinin banka hesabı.
balanceAlı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

KodDurumNedeni
validation_failed400Zorunlu 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_invalid422details içindeki bir anahtarı o ülke ve para birimine giden hiçbir rota istemiyor.
iban_invalid422IBAN kontrol hanesinden geçmiyor.
proof_required422proof_reference olmadan bir own_account.
beneficiary_not_found404Bu kimlikle size ait bir alıcı yok.
customer_suspended403Hesabınız askıda; yalnızca okuyabilir.
customer_not_active403Hesabınız henüz açılmadı ya da kapalı.

Sonraki adımlar

Bu sayfada