Doğrulama
KYC ya da KYB'yi API ile tamamlayın; profil ve belgelerden koşullara, gönderime ve incelemeye kadar. Her durumun hangi çağrılara izin verdiğini öğrenin.
Bir hesap para hareket ettirmeden önce due diligence'tan geçer: bir profil, onu kanıtlayan belgeler, kabul ettiği koşullar ve bir inceleme. Aynı endpoint'ler hem müşteri panelindeki doğrulama ekranlarına hem de sizin sisteminize hizmet eder.
Bu endpoint'leri kim çağırır
Şirketiniz kendi doğrulamasını müşteri panelinde tamamlar: API anahtarları ancak hesap aktif olduktan sonra oluşturulabilir. Bir Platform, End Customer'larını kendi sisteminden doğrulamak için bu endpoint'leri Apex-End-Customer başlığıyla kullanır. Aşağıdaki örnekler bunu yapar; başlık olmadan aynı çağrılar sizin hesabınız üzerinde çalışır.
Durumlar
state | standing | Ne oluyor |
|---|---|---|
profile_pending | onboarding | Profili doldurur, belgeleri yükler ve koşulları kabul edersiniz. |
profile_review | onboarding | Gönderildi. Compliance inceliyor. Profil, belgeler ve koşullar kilitlidir. |
contract_pending | onboarding | Onaylandı; koşullarımızın kabul edilmesi bekleniyor. Yalnızca doğrudan müşteriler. |
provider_onboarding | onboarding | Başvuru Provider'larda. Hesap ilk onayla açılır. |
active | active | Açık: tüm endpoint'ler kullanılabilir. |
suspended | suspended | Salt okunur. |
rejected | closed | Başvuru kabul edilmedi. |
Bir End Customer'da contract_pending adımı yoktur: yolu profile_pending, profile_review, provider_onboarding, active şeklindedir.
Her durumda hangi çağrılar yapılabilir
standing | Kullanılabilir | Geri kalan her şey |
|---|---|---|
onboarding | GET /v1/customer, GET /v1/onboarding, GET ve PUT /v1/profile, POST /v1/profile/submit, GET ve POST /v1/terms, /v1/documents | Okumalar dahil customer_not_active (403). Bakiyeler, alıcılar, teklifler ve ödemeler hesap aktif olana kadar bekler. |
active | Anahtarınızın izinlerinin izin verdiği her endpoint. | |
suspended | Tüm okumalar. | Yazma çağrıları customer_suspended (403) döner. |
closed | Hiçbiri. | Her istekte customer_not_active (403). |
Doğrulama sürecinde profil, belgeler ve koşullar yalnızca profile_pending durumunda değiştirilebilir. Sonraki her durumda bu yazma çağrıları profile_locked (409) döner.
İzinler
| Endpoint | İzin |
|---|---|
GET /v1/onboarding, GET /v1/terms | customer:read |
GET ve PUT /v1/profile, POST /v1/profile/submit, POST /v1/terms, tüm /v1/documents endpoint'leri | customer:profile:write |
Nerede olduğunuzu okuyun
GET /v1/onboarding, sonraki adımın bağlı olduğu her şeyi tek çağrıda döner.
curl "$APEX_BASE_URL/v1/onboarding" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Apex-End-Customer: $END_CUSTOMER_ID"{
"type": "business",
"state": "profile_pending",
"standing": "onboarding",
"requested_fields": [],
"missing_fields": [
{ "field": "business.registration_number", "message": "required" },
{ "field": "business.corridors", "message": "at least one corridor" }
],
"documents": [
{ "kind": "certificate_of_incorporation", "subject_kind": "business", "uploaded": false },
{ "kind": "proof_of_address", "subject_kind": "business", "uploaded": true },
{ "kind": "government_id", "subject_kind": "ubo", "subject_ref": "Ada Brooks", "uploaded": false }
],
"terms_accepted": false,
"providers": []
}| Alan | Anlamı |
|---|---|
state, standing | Bkz. Durumlar. |
note | Compliance'ın profili geri gönderirken yazdığı not, kelimesi kelimesine. Aksi halde gelmez. |
requested_fields | Compliance'ın yeniden bakmanızı istediği alanlar. |
missing_fields | Kaydedilen profilde hâlâ eksik olanlar, alan yoluyla. Profil tamamsa boştur. |
documents | Gönderimin istediği belgeler, her biri uploaded ile. |
terms_accepted | Geçerli tüm koşulların kabul edilip edilmediği. |
providers | Her Provider'daki başvuru: submitted, info_required, approved, rejected ya da terminated. |
missing_fields boş, her belge uploaded ve terms_accepted değeri true olduğunda gönderebilirsiniz.
Profili kaydedin
PUT /v1/profile bir taslak kaydeder. Taslak eksik olabilir: durum profile_pending olduğu sürece istediğiniz kadar kaydedin. Yalnızca hesabın türüne ait taraf saklanır: business ya da individual. GET /v1/profile taslağı ya da son gönderimi döner.
curl -X PUT "$APEX_BASE_URL/v1/profile" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Apex-End-Customer: $END_CUSTOMER_ID" \
-H "Content-Type: application/json" \
-d '{
"data": {
"business": {
"legal_name": "Harbor Crafts LLC",
"registration_number": "7734120",
"address": {
"line1": "100 Pier Avenue",
"city": "Wilmington",
"region": "DE",
"postal_code": "19801",
"country": "US"
},
"entity_type": "llc",
"ubos": [
{ "name": "Ada Brooks", "country": "US", "share_percent": "60" }
],
"authorised_persons": [
{ "name": "Ada Brooks", "email": "ada@harborcrafts.example.com", "role": "CEO" }
],
"expected_monthly_volume": { "amount": "50000", "asset": "USDC" },
"corridors": ["US:USDC>DE:EUR"]
}
}
}'Şirket profili
| Alan | Gönderimde zorunlu | Notlar |
|---|---|---|
legal_name | Evet | |
registration_number | Evet | |
address | Evet | line1, city ve country zorunlu; line2, region ve postal_code isteğe bağlı. region, bir ISO 3166-2 kodunun alt bölüm kısmıdır; örneğin DE ya da CA. |
ubos | En az bir | Her nihai faydalanıcı (UBO): name, country, share_percent; isteğe bağlı date_of_birth, nationality, address. |
authorised_persons | En az bir | Şirket adına işlem yapan her kişi: name, email, isteğe bağlı role. |
expected_monthly_volume | Evet | Bir varlıkta pozitif bir tutar; örneğin { "amount": "50000", "asset": "USDC" }. |
corridors | En az bir | Kullanmayı planladığınız koridorlar; örneğin US:USDC>DE:EUR. |
tax_id, phone, website, date_established, entity_type | Hayır | phone uluslararası biçimde (+13125550100), website bir https adresi, tarihler YYYY-MM-DD, entity_type şunlardan biri: corporation, llc, partnership, sole_proprietorship, trust, other. Bir Provider bunları isteyebilir. |
control_persons | Hayır | Şirketi kontrol eden kişiler: name; isteğe bağlı title, date_of_birth, nationality, tax_id, address. |
Şirketin address.country değeri, hesabın kendi ülkesi olmalıdır.
Bireysel profil
| Alan | Gönderimde zorunlu |
|---|---|
full_name | Evet |
date_of_birth | Evet, YYYY-MM-DD olarak |
nationality | Evet, iki harfli ülke kodu |
address | Evet, şirkettekiyle aynı; country değeri hesabın kendi ülkesi olmalı |
Belgeleri yükleyin
POST /v1/documents, multipart/form-data gövde alır:
| Parça | Anlamı |
|---|---|
file | Dosya: PDF, JPEG ya da PNG (içeriğine göre değerlendirilir), en fazla 10 MB. |
kind | certificate_of_incorporation, articles_or_by_laws, certificate_of_good_standing, operating_agreement, proof_of_address, ownership_structure, government_id ya da other. |
subject_kind | Belgenin kimin hakkında olduğu: business, ubo, control_person ya da individual. |
subject_ref | Yalnızca ubo ve control_person için: kişinin adı, profildekiyle birebir aynı. |
Bir gönderim şunları ister:
| Hesap | Belgeler |
|---|---|
| Şirket | business hakkında certificate_of_incorporation (kuruluş belgesi) ve proof_of_address (adres belgesi); her UBO ve her kontrol eden kişi için bir government_id (resmî kimlik belgesi). |
| Bireysel | individual hakkında government_id ve proof_of_address. |
İncelemeye yardımcı olacaksa diğer türler de eklenebilir; bir Provider bunları isteyebilir.
curl -X POST "$APEX_BASE_URL/v1/documents" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Apex-End-Customer: $END_CUSTOMER_ID" \
-F "file=@ada-brooks-passport.pdf" \
-F "kind=government_id" \
-F "subject_kind=ubo" \
-F "subject_ref=Ada Brooks"{
"id": "5e8a1c3b-7d9f-4b2e-a6c4-0f1e2d3c4b5a",
"kind": "government_id",
"subject_kind": "ubo",
"subject_ref": "Ada Brooks",
"file_name": "ada-brooks-passport.pdf",
"mime": "application/pdf",
"size_bytes": 482113,
"sha256": "4c1f0b7e9a2d38c56e7f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d",
"version": 1,
"current": true,
"uploaded_at": "2026-11-12T09:12:00Z"
}- Aynı kişi ya da şirket hakkında aynı türde yeni bir dosya bir sonraki
versionolur. Önceki dosya saklanır;currentdeğerifalseolur vesuperseded_atalır. Hiçbir şey silinmez. - Bu endpoint
Idempotency-Keyalmaz: iki kez gönderilen bir yükleme yalnızca bir sürüm daha demektir. GET /v1/documentsher sürümü en yenisi önce listeler.GET /v1/documents/{id}/contenttek bir dosyayı ek olarak indirir.- Profil gönderildikten sonra yüklemeler
profile_locked(409) ile reddedilir.
Koşulları kabul edin
GET /v1/terms kabul edilecek koşulları listeler: doğrudan bir müşteri için bizim koşullarımızı ve hesabın gönderileceği her Provider'ın koşullarını. Bir End Customer yalnızca Provider'ların koşullarını kabul eder. Her url adresini kabul eden kişiye gösterin.
{
"version": "provider:bvnk@fake-1|provider:zerohash@fake-1",
"documents": [
{ "id": "provider:bvnk", "provider": "bvnk", "url": "https://example.invalid/terms/bvnk", "version": "fake-1" },
{ "id": "provider:zerohash", "provider": "zerohash", "url": "https://example.invalid/terms/zerohash", "version": "fake-1" }
],
"accepted": false
}Kabul etmek için setin version değerini okuduğunuz gibi geri gönderin. Siz okuduktan sonra set değiştiyse çağrı terms_changed (409) döner: yeniden okuyun ve yeni koşulları gösterin.
curl -X POST "$APEX_BASE_URL/v1/terms" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Apex-End-Customer: $END_CUSTOMER_ID" \
-H "Content-Type: application/json" \
-d '{ "version": "provider:bvnk@fake-1|provider:zerohash@fake-1" }'Her kabul, kimin kabul ettiği ve ne zaman olduğuyla kaydedilir; yanıt her belgede accepted_at taşır. Koşullar gönderimden önce profile_pending durumunda ya da contract_pending durumunda kabul edilebilir.
Gönderin
POST /v1/profile/submit her şeyi incelemeye gönderir ve GET /v1/onboarding ile aynı görünümü, artık profile_review durumunda, döner.
curl -X POST "$APEX_BASE_URL/v1/profile/submit" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Apex-End-Customer: $END_CUSTOMER_ID"Bir şey eksikse çağrı profile_invalid (422) döner ve her alanı ve belgeyi details içinde adlandırır:
{
"code": "profile_invalid",
"message": "the Compliance Profile is incomplete",
"correlation_id": "c0a8012e-6b1f-4d2a-9e3c-7f5a4b3c2d1e",
"details": [
{ "field": "business.registration_number", "message": "required" },
{ "field": "documents.ubo.Ada Brooks.government_id", "message": "required" }
]
}| Kod | Durum | Nedeni |
|---|---|---|
profile_invalid | 422 | Alanlar ya da belgeler eksik veya hatalı; details alanına bakın. |
profile_missing | 422 | Henüz hiçbir şey kaydedilmedi. |
terms_not_accepted | 409 | Geçerli koşulların hepsi kabul edilmedi. |
country_mismatch | 422 | Adres, hesabın ülkesinden farklı bir ülkede. |
country_not_accepted | 422 | O ülkeden artık müşteri kabul etmiyoruz. |
profile_locked | 409 | Profil zaten gönderildi. |
İnceleme ve Provider'lar
Compliance gönderimi inceler. Sonuç GET /v1/onboarding yanıtında görünür:
| Sonuç | Ne görürsünüz | Ne yapmalı |
|---|---|---|
| Onaylandı | state, provider_onboarding durumuna geçer (koşullarımız beklerken contract_pending). | Hiçbir şey. Başvuru Provider'lara gider. |
| Ek bilgi gerekiyor | state yeniden profile_pending olur; note ve requested_fields ile. | Notun istediğini düzeltin, gerekirse yeni belge yükleyin ve yeniden gönderin. |
| Reddedildi | state rejected, standing closed olur. | Artık her istek customer_not_active döner. Hesap yöneticinizle görüşün. |
provider_onboarding durumunda providers her başvurunun ilerlemesini gösterir. Bir Provider hesabı onayladığı anda hesap active olur ve para endpoint'leri açılır. Ödemeler yalnızca hesabı onaylamış Provider'ların rotalarını kullanabilir; diğerleri üzerinden istenen bir teklif onboarding_required döner.
Bir End Customer'ın ilerlemesini, onun başlığıyla GET /v1/onboarding ya da GET /v1/end-customers/{id} ile okuyun. Doğrulama değişiklikleri için webhook yoktur.
Belge hataları
| Kod | Durum | Nedeni |
|---|---|---|
document_file_required | 400 | file parçası yok. |
document_empty | 422 | Dosya boş. |
document_too_large | 413 | Dosya 10 MB'tan büyük. |
document_type_not_allowed | 422 | İçerik PDF, JPEG ya da PNG değil. |
document_kind_unknown | 422 | Bilinmeyen kind. |
document_subject_invalid | 422 | Bilinmeyen subject_kind; ya da subject_ref eksik veya ait olmadığı yerde verilmiş. |
document_limit_reached | 422 | Hesap, tutabileceği en fazla belge sürümüne ya da boyuta ulaştı. |
document_not_found | 404 | Bu kimlikle hesaba ait bir belge yok. |
document_busy | 503 | Şu anda çok fazla dosya işleniyor. Kısa süre sonra tekrar deneyin. |