İçeriğe geç
Apex Settlement

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

statestandingNe oluyor
profile_pendingonboardingProfili doldurur, belgeleri yükler ve koşulları kabul edersiniz.
profile_reviewonboardingGönderildi. Compliance inceliyor. Profil, belgeler ve koşullar kilitlidir.
contract_pendingonboardingOnaylandı; koşullarımızın kabul edilmesi bekleniyor. Yalnızca doğrudan müşteriler.
provider_onboardingonboardingBaşvuru Provider'larda. Hesap ilk onayla açılır.
activeactiveAçık: tüm endpoint'ler kullanılabilir.
suspendedsuspendedSalt okunur.
rejectedclosedBaş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

standingKullanılabilirGeri kalan her şey
onboardingGET /v1/customer, GET /v1/onboarding, GET ve PUT /v1/profile, POST /v1/profile/submit, GET ve POST /v1/terms, /v1/documentsOkumalar dahil customer_not_active (403). Bakiyeler, alıcılar, teklifler ve ödemeler hesap aktif olana kadar bekler.
activeAnahtarınızın izinlerinin izin verdiği her endpoint.
suspendedTüm okumalar.Yazma çağrıları customer_suspended (403) döner.
closedHiç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/termscustomer:read
GET ve PUT /v1/profile, POST /v1/profile/submit, POST /v1/terms, tüm /v1/documents endpoint'lericustomer: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"
200 OK
{
  "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": []
}
AlanAnlamı
state, standingBkz. Durumlar.
noteCompliance'ın profili geri gönderirken yazdığı not, kelimesi kelimesine. Aksi halde gelmez.
requested_fieldsCompliance'ın yeniden bakmanızı istediği alanlar.
missing_fieldsKaydedilen profilde hâlâ eksik olanlar, alan yoluyla. Profil tamamsa boştur.
documentsGönderimin istediği belgeler, her biri uploaded ile.
terms_acceptedGeçerli tüm koşulların kabul edilip edilmediği.
providersHer 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

AlanGönderimde zorunluNotlar
legal_nameEvet
registration_numberEvet
addressEvetline1, 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.
ubosEn az birHer nihai faydalanıcı (UBO): name, country, share_percent; isteğe bağlı date_of_birth, nationality, address.
authorised_personsEn az birŞirket adına işlem yapan her kişi: name, email, isteğe bağlı role.
expected_monthly_volumeEvetBir varlıkta pozitif bir tutar; örneğin { "amount": "50000", "asset": "USDC" }.
corridorsEn az birKullanmayı planladığınız koridorlar; örneğin US:USDC>DE:EUR.
tax_id, phone, website, date_established, entity_typeHayırphone 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_personsHayı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

AlanGönderimde zorunlu
full_nameEvet
date_of_birthEvet, YYYY-MM-DD olarak
nationalityEvet, iki harfli ülke kodu
addressEvet, şirkettekiyle aynı; country değeri hesabın kendi ülkesi olmalı

Belgeleri yükleyin

POST /v1/documents, multipart/form-data gövde alır:

ParçaAnlamı
fileDosya: PDF, JPEG ya da PNG (içeriğine göre değerlendirilir), en fazla 10 MB.
kindcertificate_of_incorporation, articles_or_by_laws, certificate_of_good_standing, operating_agreement, proof_of_address, ownership_structure, government_id ya da other.
subject_kindBelgenin kimin hakkında olduğu: business, ubo, control_person ya da individual.
subject_refYalnızca ubo ve control_person için: kişinin adı, profildekiyle birebir aynı.

Bir gönderim şunları ister:

HesapBelgeler
Şirketbusiness 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).
Bireyselindividual 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"
201 Created
{
  "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 version olur. Önceki dosya saklanır; current değeri false olur ve superseded_at alır. Hiçbir şey silinmez.
  • Bu endpoint Idempotency-Key almaz: iki kez gönderilen bir yükleme yalnızca bir sürüm daha demektir.
  • GET /v1/documents her sürümü en yenisi önce listeler. GET /v1/documents/{id}/content tek 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.

GET /v1/terms, 200 OK
{
  "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:

422 Unprocessable Entity
{
  "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" }
  ]
}
KodDurumNedeni
profile_invalid422Alanlar ya da belgeler eksik veya hatalı; details alanına bakın.
profile_missing422Henüz hiçbir şey kaydedilmedi.
terms_not_accepted409Geçerli koşulların hepsi kabul edilmedi.
country_mismatch422Adres, hesabın ülkesinden farklı bir ülkede.
country_not_accepted422O ülkeden artık müşteri kabul etmiyoruz.
profile_locked409Profil 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üzNe 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 gerekiyorstate yeniden profile_pending olur; note ve requested_fields ile.Notun istediğini düzeltin, gerekirse yeni belge yükleyin ve yeniden gönderin.
Reddedildistate 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ı

KodDurumNedeni
document_file_required400file parçası yok.
document_empty422Dosya boş.
document_too_large413Dosya 10 MB'tan büyük.
document_type_not_allowed422İçerik PDF, JPEG ya da PNG değil.
document_kind_unknown422Bilinmeyen kind.
document_subject_invalid422Bilinmeyen subject_kind; ya da subject_ref eksik veya ait olmadığı yerde verilmiş.
document_limit_reached422Hesap, tutabileceği en fazla belge sürümüne ya da boyuta ulaştı.
document_not_found404Bu kimlikle hesaba ait bir belge yok.
document_busy503Şu anda çok fazla dosya işleniyor. Kısa süre sonra tekrar deneyin.

Sonraki adımlar

Bu sayfada