İçeriğe geç
Apex Settlement

Ödeme gönderme

Bir alıcıya yapılacak ödeme için teklif alın, bir teklifi ödemeye dönüştürün ve para ulaşana kadar izleyin.

Para göndermek üç çağrıdan oluşur: teklif istersiniz, tekliflerden birini kabul edersiniz ve oluşan ödemeyi tamamlanana kadar izlersiniz.

Teklif alın

POST /v1/quotes, ödemeyi taşıyabilecek her rota için fiyat verir.

Kabul edin

POST /v1/payouts, seçtiğiniz teklifi bir ödemeye dönüştürür.

İzleyin

GET /v1/payouts/{id} ya da payout.updated webhook'u ödemenin nerede olduğunu söyler.

Başlamadan önce

  • Hesabınız active olmalı. O zamana kadar para işlemi yapan her endpoint customer_not_active döner. Bkz. Doğrulama.
  • API anahtarınız customer:payouts:create iznini taşımalı. Ödemeleri geri okumak için customer:read da gerekir.
  • Alıcı kayıtlı ve verified olmalı. Bkz. Alıcılar.
  • Bakiyeniz, gönderilecek tutarı rotanın başladığı Provider'da tutuyor olmalı. Bkz. Bakiyeler ve para yatırma.

Teklif isteyin

Ne gönderdiğinizi ve kime gönderdiğinizi belirtirsiniz. Hedefi hiçbir zaman göndermezsiniz: hedef, alıcının ülkesi ve para birimidir. Kaynak ülke ise sizin ülkenizdir.

Alan

Tür

ABD'de bir şirket olan Tom, Birleşik Krallık'taki bir tedarikçisine 1000 USDC gönderiyor:

curl -X POST "$APEX_BASE_URL/v1/quotes" \
  -H "Authorization: Bearer $APEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_asset": "USDC",
    "amount": "1000",
    "beneficiary_id": "6f1c2a9e-3b7d-4c58-9a21-0d4e8b7f5c13",
    "purpose": "supplier"
  }'

Yanıt 201 Created ve bir teklif setidir:

201 Created
{
  "quote_set_id": "0b9d6c1e-7f2a-4e35-8c41-5a6b9e0d2f78",
  "quotes": [
    {
      "quote_id": "qt1.eyJkIjoiMGI5ZDZjMWUtN2YyYS00ZTM1…",
      "send": { "amount": "1000", "asset": "USDC" },
      "receive": { "amount": "788.71", "asset": "GBP" },
      "fees": [
        { "provider": "bvnk", "component": "provider", "amount": { "amount": "1", "asset": "USDC" } },
        { "provider": "bvnk", "component": "provider", "amount": { "amount": "0.5", "asset": "GBP" } }
      ],
      "rates": [
        { "provider": "bvnk", "rate": "0.79" },
        { "provider": "bvnk", "rate": "1" }
      ],
      "providers": ["bvnk"],
      "settlement_seconds": 120,
      "estimated_arrival": "2026-11-12T10:02:00Z",
      "expires_at": "2026-11-12T10:01:00Z",
      "labels": ["cheapest", "fastest"]
    }
  ],
  "server_time": "2026-11-12T10:00:00Z"
}

Bir teklifte neler var

AlanAnlamı
quote_idBu teklifi kabul etmek için geri gönderdiğiniz değer. İçeriğine bakmayın: imzalıdır ve yalnızca sizin hesabınız kullanabilir.
sendBakiyenizden çıkacak tutar, ücretler dahil.
receiveTüm ücretlerden sonra alıcıya ulaşan tutar.
feesHer ücret, alındığı varlıkla ayrı bir satırda.
ratesHer Provider'ın kuru, hiç değiştirilmeden; rotanın her adımı için bir satır.
providersRotayı yürüten Provider'lar, sırasıyla.
settlement_secondsRotanın adımlarının toplam süresi, Provider'ların bildirdiği şekliyle.
estimated_arrivalserver_time artı settlement_seconds. Bir tahmindir, taahhüt değildir.
expires_atTeklifi kabul edebileceğiniz son an.
labelscheapest en çok ulaştıran teklifi, fastest en erken varanı işaretler. Bir teklif ikisini birden taşıyabilir.

server_time, yanıtın üretildiği an (UTC). Bir teklifin kalan süresini kendi saatinize göre değil, bu değere göre hesaplayın.

Ücretler

Ücretler üç bileşenle gelir:

componentKim alır
service_feeÖdeme için bizim hizmet ücretimiz. provider alanı yoktur ve her zaman gönderilen varlıktadır. İlk adımdan önce tutardan düşülür.
providerBir Provider'ın bir adım için aldığı ücret, o adımın giriş varlığında.
networkBir Provider'ın bir adım için yansıttığı ağ ücreti.

Teklif her şey dahildir: receive, tüm satırlar düşüldükten sonra kalan tutardır. Yukarıdaki örnekte ilk adım 1 USDC ücret alır ve kalanı çevirir: 999 × 0,79 = 789,21 GBP. Ödeme adımı 0,5 GBP alır; alıcıya 788,71 GBP ulaşır.

Sandbox'tan örnekler

Sandbox bu koridorları sabit, örnek amaçlı kur ve ücretlerle, hizmet ücreti olmadan çalıştırır:

GönderdiğinizAlıcıRotaAlıcıya ulaşan
1000 USDCDE, EURÇevrim, ardından SEPA Instant918.58 EUR
1000 EURCDE, EURÇevrim, ardından SEPA Instant998.5 EUR
1000 USDCGB, GBPÇevrim, ardından Faster Payments788.71 GBP
1000 USDCUS, USDÇevrim, ardından RTP998 USD
1000 USDTPK, PKR (banka hesabı)ABD'de USD'ye satılır, ardından Pakistan'da ödenir277664.5 PKR

Almanya'daki bir IBAN için iki teklif alırsınız: SEPA Instant ve SEPA Credit Transfer. İkisi de 918.58 EUR ulaştırır. Instant yaklaşık iki dakikada, havale ise yaklaşık bir günde varır. İki teklif aynı tutarı ulaştırdığında cheapest etiketini yalnızca biri taşır; bu yüzden estimated_arrival değerini de karşılaştırın.

ABD'den Pakistan'a koridor, ücretlerin nasıl biriktiğini gösterir. Pakistan'da bir şirket olan Lina, Tom'un alıcısıdır. %0,5 artı 1 USDT hizmet ücretiyle Tom'un 1000 USDT'si şöyle ilerler:

AdımHesapSonuç
Hizmet ücreti1000 × %0,5 + 1 = 6 USDTKalan 994 USDT
1. adım, USD'ye satışücret 1 USDT, kur 1993 USD
2. adım, PKR olarak ödemeücret 2 USD, kur 278,5: 991 × 278,5275993.5 PKR

Teklif üç ücret satırı listeler: 6 USDT için service_fee, ardından her adım için birer provider satırı, 1 USDT ve 2 USD. Hizmet ücreti olmadan aynı ödeme 277664.5 PKR ulaştırır.

Teklifin ömrü

Teklifler kısa ömürlüdür: sandbox'ta yaklaşık bir dakika. Her teklifte expires_at değerini okuyun ve ondan önce kabul edin. Süresi dolduysa yeni teklif isteyin.

Her teklif bir kez kabul edilebilir. Aynı tekliften ikinci bir ödeme quote_already_used ile reddedilir.

Teklif gelmediğinde

Ödemeyi taşıyabilecek bir şey yoksa quotes boş gelir ve unavailable_reason nedenini tek kelimeyle söyler. Yanıt yine 201'dir.

201 Created
{
  "quote_set_id": "5d2a8f0c-1e6b-4b7a-9c3d-8f4e2a1b6c90",
  "quotes": [],
  "unavailable_reason": "funds_at_other_provider",
  "deposit_at": ["bvnk"],
  "server_time": "2026-11-12T10:00:00Z"
}
unavailable_reasonAnlamıNe yapmalı
beneficiary_not_verifiedAlıcı hâlâ pending_verification durumunda, blocked ya da şu an ödeme alamayan başka bir müşteri. quote_set_id gelmez.beneficiary.updated webhook'unun verified demesini bekleyin ya da başka bir alıcı seçin.
onboarding_requiredOlası her rotadaki bir Provider hesabınızı henüz onaylamadı.İstekte değiştirilecek bir şey yok. Hesap yöneticinizle görüşün; başvuru hâlâ inceleniyor olabilir.
funds_at_other_providerTutarı tutuyorsunuz ama rotaların başladığı Provider'da değil. deposit_at nereye yatırmanız gerektiğini söyler.Gönderilecek varlığı deposit_at içindeki Provider'lardan birine yatırın, sonra yeniden teklif isteyin. Bkz. Bakiyeler ve para yatırma.
temporarily_unavailableBir rota bizim tarafımızda bir süreliğine kapalı.Yapmanız gereken bir şey yok. Daha sonra tekrar deneyin.
amount_out_of_rangeTutar rotaların kabul ettiği aralığın altında ya da üstünde, veya ücretleri karşılamayacak kadar küçük.Farklı bir tutar deneyin.
no_routeŞu anda bu koridora ya da bu alıcıya hizmet veren bir rota yok.Hesap yöneticinizle görüşün.

Birden fazla neden geçerliyse, önce üzerinde işlem yapabileceğiniz neden gelir; sıra şöyledir: beneficiary_not_verified, onboarding_required, funds_at_other_provider, temporarily_unavailable, amount_out_of_range, no_route.

deposit_at yalnızca funds_at_other_provider ile gelir ve o durumda hiçbir zaman boş değildir. Değerleri, GET /v1/deposit-instructions ve GET /v1/balances yanıtlarındaki Provider anahtarlarıyla aynıdır.

Tutarı hiçbir yerde tutmuyorsanız

funds_at_other_provider yalnızca tutarı bir Provider'da zaten tutuyorsanız görünür. Hiçbirinde tutmuyorsanız yine teklif alırsınız ve ödeme bir para yatırmayı bekler (aşağıya bakın). Önce bakiyenizi fonlayın, sonra teklif isteyin.

POST /v1/quotes hataları

KodDurumNedeni
validation_failed400Zorunlu bir alan eksik ya da purpose veya preference bilinmeyen bir değer taşıyor.
bad_amount422amount pozitif bir ondalık sayı değil.
amount_scale422amount, varlığın kabul ettiğinden fazla ondalık taşıyor.
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ı.

quote_unavailable ya da funds_unavailable gibi bir 5xx yanıtı, bir Provider'ın ya da bir bağımlılığın zamanında yanıt vermediği anlamına gelir. Artan aralıklarla tekrar deneyin. Hata biçimi için bkz. Hatalar.

Bir teklifi kabul edin

Seçtiğiniz quote_id değerini POST /v1/payouts ile gönderin. Idempotency-Key başlığı zorunludur. Oluşturmak istediğiniz her ödeme için bir anahtar üretin ve tekrar denediğinizde aynı anahtarı gönderin: tekrar deneme ikinci bir ödeme oluşturmaz, ilk ödemeyi döner. Bkz. Idempotency.

IDEMPOTENCY_KEY=$(uuidgen)

curl -X POST "$APEX_BASE_URL/v1/payouts" \
  -H "Authorization: Bearer $APEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{ "quote_id": "qt1.eyJkIjoiMGI5ZDZjMWUtN2YyYS00ZTM1…" }'
201 Created
{
  "id": "3c8e5b1a-9d24-4f6e-b7a0-2e1f4c6d8a95",
  "state": "processing",
  "send": { "amount": "1000", "asset": "USDC" },
  "receive": { "amount": "788.71", "asset": "GBP" },
  "fees": [
    { "provider": "bvnk", "component": "provider", "amount": { "amount": "1", "asset": "USDC" } },
    { "provider": "bvnk", "component": "provider", "amount": { "amount": "0.5", "asset": "GBP" } }
  ],
  "rates": [
    { "provider": "bvnk", "rate": "0.79" },
    { "provider": "bvnk", "rate": "1" }
  ],
  "beneficiary": {
    "id": "6f1c2a9e-3b7d-4c58-9a21-0d4e8b7f5c13",
    "name": "Northwind Supplies Ltd",
    "country": "GB",
    "party_type": "business"
  },
  "delivered_to": "bank_account",
  "legs": [
    { "index": 0, "provider": "bvnk", "from": "USDC", "to": "GBP", "state": "pending" },
    { "index": 1, "provider": "bvnk", "from": "GBP", "to": "GBP", "state": "pending" }
  ],
  "initiated_by": { "actor": "customer", "kind": "api_key", "id": "9a7b3c21-5d4e-4f60-8b19-c2d3e4f5a6b7" },
  "initiated_by_you": true,
  "cancellable": false,
  "created_at": "2026-11-12T10:00:20Z",
  "updated_at": "2026-11-12T10:00:20Z"
}

Ödeme, teklifin tutarlarını, ücretlerini ve kurlarını korur. legs, rotanın adımlarıdır; sırasıyla ve her biri kendi durumuyla: pending, processing, completed, failed, returned ya da cancelled. delivered_to değeri bank_account'tur; rota başka bir müşterinin platform bakiyesine ekliyorsa balance olur (bkz. Ödeme alma).

Yanıtta hangi durum gelir

Yanıttaki stateNeden
processingBakiyeniz gönderilecek tutarı karşıladı. Tutar hemen ayrıldı ve rota başladı.
acceptedRotanın ilk Provider'ındaki bakiyeniz gönderilecek tutarı henüz karşılamıyor. Ödeme oraya bir para yatırmayı bekler.
awaiting_approvalOnay kurallarınızdan biri ödemeyi ikinci bir kişi için bekletiyor. Bakiyenizden henüz bir şey ayrılmadı.

POST /v1/payouts hataları

KodDurumNedeni ve ne yapmalı
quote_token_invalid422quote_id değiştirilmiş ya da başka bir hesaba ait. quote_id değerini teklif setinde geldiği gibi kullanın.
quote_expired422Teklifin süresi doldu ya da rotası artık başlayamıyor. Yeni teklif isteyin.
quote_already_used409Bu teklif için zaten bir ödeme var. Bu sizin tekrar denemenizse, o ödemeyi geri almak için ilk Idempotency-Key değerini gönderin. Değilse yeniden teklif isteyin.
beneficiary_changed409Alıcı başka bir müşteri ve siz teklif aldıktan sonra para alacağı hesabı değiştirdi. Yeniden teklif isteyin; yeni teklif yeni hesaba öder.
beneficiary_unavailable409Alıcı, şu an ödeme alamayan başka bir müşteri. Daha sonra deneyin ya da bir Alım Hesabı seçmesini isteyin.
beneficiary_not_verified422Alıcı engellendi ya da artık doğrulanmış değil.
customer_suspended403Hesabınız askıda.

Ödemeyi izleyin

Durumlar

DurumAnlamıSon durum mu
awaiting_approvalOnay kurallarınız ödemeyi şirketinizden ikinci bir kişi için bekletiyor. Bakiyenizden bir şey ayrılmaz. Önce teklifin süresi dolarsa iptal edilir.Hayır
acceptedKabul edildi; rotanın ilk Provider'ındaki bakiyenizin tutarı karşılamasını bekliyor. Henüz bir şey ayrılmadı. Fonlanmadan teklifin süresi dolarsa iptal edilir.Hayır
fundedGönderilecek tutar, ücretler dahil, bakiyenizden ayrıldı. GET /v1/balances yanıtında held altında görünür.Hayır
processingRotanın adımları çalışıyor; olası uyum kontrolü de buna dahil.Hayır
completedSon adım tamamlandı: alıcıya ödendi.Evet
failedBir adım başarısız oldu. Operasyon ekibimiz adımı yeniden denerken ya da ödemeyi iade ederken tutar ayrılmış kalır.Hayır
refundedAyrılan tutar kullanılabilir bakiyenize döndü.Evet
cancelledBir şey ayrılmadan kapandı. Bakiyenizden hiçbir şey çıkmadı.Evet

GET /v1/payouts/{id} buna bir timeline ekler: ödemenin ulaştığı her durum, zamanı ve kimin (by) yaptığı. by.actor değeri customer (sizin kişileriniz ya da anahtarlarınız; kind ve id ile), operations ya da system olur. Bir onaylayıcı ödemeyi geçirdiğinde, accepted kaydı onu adlandırır.

Tamamlanmış bir ödemenin zaman çizgisi
{
  "timeline": [
    { "state": "accepted", "at": "2026-11-12T10:00:20Z", "by": { "actor": "customer", "kind": "api_key", "id": "9a7b3c21-5d4e-4f60-8b19-c2d3e4f5a6b7" } },
    { "state": "funded", "at": "2026-11-12T10:00:20Z", "by": { "actor": "customer", "kind": "api_key", "id": "9a7b3c21-5d4e-4f60-8b19-c2d3e4f5a6b7" } },
    { "state": "processing", "at": "2026-11-12T10:00:20Z", "by": { "actor": "customer", "kind": "api_key", "id": "9a7b3c21-5d4e-4f60-8b19-c2d3e4f5a6b7" } },
    { "state": "completed", "at": "2026-11-12T10:02:05Z", "by": { "actor": "system" } }
  ]
}

Onay beklerken

Şirketinizin yöneticileri onay kurallarını müşteri panelinde belirler: varlık başına bir eşik tutar, yeni bir alıcıya ilk ödeme ya da ikisi birden. Herhangi bir kural tutarsa POST /v1/payouts yanıtı awaiting_approval olur.

API anahtarları asla onaylamaz

Bekleyen bir ödemeyi müşteri panelinde bir kişi onaylar ya da reddeder. Bu kişinin onaylayıcı ya da yönetici rolü olmalıdır. Ödemeyi başlatan kişi ya da ödemeyi başlatan API anahtarını oluşturan kişi olamaz. Hiçbir API anahtarı onaylama iznini taşıyamaz; entegrasyonunuz kendi ödemelerini onaylayamaz.

Entegrasyonunuzun gördükleri:

  • Onaylandığında ödeme accepted durumuna geçer ve bakiyeniz karşılıyorsa hemen fonlanır.
  • Reddedildiğinde cancelled olur; cancelled kaydının by değeri reddeden kişidir.
  • Kimse onaylamadan teklifin süresi dolarsa ödeme system tarafından iptal edilir. Teklifler kısa ömürlü olduğundan onayların hızlı verilmesi gerekir; yoksa yeniden teklif isteyip yeni bir ödeme oluşturun.
  • Beklerken alıcı engellendiyse, alıcı müşteri hesabını değiştirdiyse ya da hesabınız askıya alındıysa, onay ödemeyi göndermek yerine iptal eder.

Para beklerken

accepted durumundaki bir ödeme, rotanın ilk Provider'ındaki bakiyenizin tutarı karşılamasını bekler. Oraya yapılan bir para yatırma onu fonlar; en eski ödeme önce. Önce teklifin süresi dolarsa ödeme iptal edilir. Pratikte: önce para yatırın, sonra teklif isteyin.

İptal

POST /v1/payouts/{id}/cancel, henüz bir şey ayrılmamış bir ödemeyi kapatır: awaiting_approval ya da accepted durumundakileri. Ödemenin cancellable alanı çağrının şu an mümkün olup olmadığını söyler. Ödeme funded olduktan sonra para yoldadır ve iptal payout_not_cancellable (409) döner.

curl -X POST "$APEX_BASE_URL/v1/payouts/3c8e5b1a-9d24-4f6e-b7a0-2e1f4c6d8a95/cancel" \
  -H "Authorization: Bearer $APEX_API_KEY"

İptal edilen bir ödemenin teklifi de onunla kalır: yeniden göndermek için yeni teklif isteyin.

Başarısızlık ve iade

Bir adım başarısız olduğunda ödeme failed durumuna geçer ve bir failure taşır:

{ "state": "failed", "failure": { "leg": 1, "code": "provider_refused" } }

leg, başarısız olan adımın index değeridir. code şunlardan biridir: provider_refused (Provider adımı reddetti), rate_moved (adım gönderilmeden önce Provider'ın fiyatı izin verilenden fazla değişti), leg_failed, leg_returned ya da leg_cancelled (Provider adımın başarısız olduğunu, iade edildiğini ya da iptal edildiğini bildirdi) veya no_connection (Provider'a ulaşılamadı).

Sizin bir şey yapmanız gerekmez. Operasyon ekibimiz ya adımı yeniden dener, ödeme processing durumuna döner; ya da iade eder. İade, ödemeyi refunded yapar ve ayrılan tutarı, ayrıldığı Provider'da kullanılabilir bakiyenize geri koyar. Tamamlanmış bir adımın gönderilen varlıkta zaten aldığı Provider ücreti geri dönmez.

Sorgulama mı, webhook mu

payout.updated webhook'una abone olun: ödemenin durumu her değiştiğinde ödemenin tamamını, imzalı olarak ve uç noktanız yanıt verene kadar yeniden denenerek alırsınız. Bkz. Webhook'lar.

Bunun yerine sorgulayacaksanız, GET /v1/payouts/{id} çağrısını artan aralıklarla yapın ve bir son duruma ulaşınca durun: completed, refunded ya da cancelled. failed bir son durum değildir.

Ödemeleri listelemek için GET /v1/payouts kullanın; en yenisi önce gelir:

Sorgu parametresiAnlamı
stateYukarıdaki durumlardan biri. processing, rotası çalışan her ödemeyi listeler.
limit1 ile 100 arası, varsayılan 50.
cursorÖnceki sayfanın next_cursor değeri. Son sayfada next_cursor gelmez.
curl "$APEX_BASE_URL/v1/payouts?state=failed&limit=20" \
  -H "Authorization: Bearer $APEX_API_KEY"

Sonraki adımlar

Bu sayfada