Ö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
activeolmalı. O zamana kadar para işlemi yapan her endpointcustomer_not_activedöner. Bkz. Doğrulama. - API anahtarınız
customer:payouts:createiznini taşımalı. Ödemeleri geri okumak içincustomer:readda gerekir. - Alıcı kayıtlı ve
verifiedolmalı. 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:
{
"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
| Alan | Anlamı |
|---|---|
quote_id | Bu 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. |
send | Bakiyenizden çıkacak tutar, ücretler dahil. |
receive | Tüm ücretlerden sonra alıcıya ulaşan tutar. |
fees | Her ücret, alındığı varlıkla ayrı bir satırda. |
rates | Her Provider'ın kuru, hiç değiştirilmeden; rotanın her adımı için bir satır. |
providers | Rotayı yürüten Provider'lar, sırasıyla. |
settlement_seconds | Rotanın adımlarının toplam süresi, Provider'ların bildirdiği şekliyle. |
estimated_arrival | server_time artı settlement_seconds. Bir tahmindir, taahhüt değildir. |
expires_at | Teklifi kabul edebileceğiniz son an. |
labels | cheapest 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:
component | Kim 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. |
provider | Bir Provider'ın bir adım için aldığı ücret, o adımın giriş varlığında. |
network | Bir 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ğiniz | Alıcı | Rota | Alıcıya ulaşan |
|---|---|---|---|
| 1000 USDC | DE, EUR | Çevrim, ardından SEPA Instant | 918.58 EUR |
| 1000 EURC | DE, EUR | Çevrim, ardından SEPA Instant | 998.5 EUR |
| 1000 USDC | GB, GBP | Çevrim, ardından Faster Payments | 788.71 GBP |
| 1000 USDC | US, USD | Çevrim, ardından RTP | 998 USD |
| 1000 USDT | PK, PKR (banka hesabı) | ABD'de USD'ye satılır, ardından Pakistan'da ödenir | 277664.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ım | Hesap | Sonuç |
|---|---|---|
| Hizmet ücreti | 1000 × %0,5 + 1 = 6 USDT | Kalan 994 USDT |
| 1. adım, USD'ye satış | ücret 1 USDT, kur 1 | 993 USD |
| 2. adım, PKR olarak ödeme | ücret 2 USD, kur 278,5: 991 × 278,5 | 275993.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.
{
"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_reason | Anlamı | Ne yapmalı |
|---|---|---|
beneficiary_not_verified | Alı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_required | Olası 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_provider | Tutarı 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_unavailable | Bir rota bizim tarafımızda bir süreliğine kapalı. | Yapmanız gereken bir şey yok. Daha sonra tekrar deneyin. |
amount_out_of_range | Tutar 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ı
| Kod | Durum | Nedeni |
|---|---|---|
validation_failed | 400 | Zorunlu bir alan eksik ya da purpose veya preference bilinmeyen bir değer taşıyor. |
bad_amount | 422 | amount pozitif bir ondalık sayı değil. |
amount_scale | 422 | amount, varlığın kabul ettiğinden fazla ondalık taşıyor. |
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ı. |
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…" }'{
"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 state | Neden |
|---|---|
processing | Bakiyeniz gönderilecek tutarı karşıladı. Tutar hemen ayrıldı ve rota başladı. |
accepted | Rotanın ilk Provider'ındaki bakiyeniz gönderilecek tutarı henüz karşılamıyor. Ödeme oraya bir para yatırmayı bekler. |
awaiting_approval | Onay kurallarınızdan biri ödemeyi ikinci bir kişi için bekletiyor. Bakiyenizden henüz bir şey ayrılmadı. |
POST /v1/payouts hataları
| Kod | Durum | Nedeni ve ne yapmalı |
|---|---|---|
quote_token_invalid | 422 | quote_id değiştirilmiş ya da başka bir hesaba ait. quote_id değerini teklif setinde geldiği gibi kullanın. |
quote_expired | 422 | Teklifin süresi doldu ya da rotası artık başlayamıyor. Yeni teklif isteyin. |
quote_already_used | 409 | Bu 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_changed | 409 | Alı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_unavailable | 409 | Alıcı, şu an ödeme alamayan başka bir müşteri. Daha sonra deneyin ya da bir Alım Hesabı seçmesini isteyin. |
beneficiary_not_verified | 422 | Alıcı engellendi ya da artık doğrulanmış değil. |
customer_suspended | 403 | Hesabınız askıda. |
Ödemeyi izleyin
Durumlar
| Durum | Anlamı | Son durum mu |
|---|---|---|
awaiting_approval | Onay 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 |
accepted | Kabul 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 |
funded | Gönderilecek tutar, ücretler dahil, bakiyenizden ayrıldı. GET /v1/balances yanıtında held altında görünür. | Hayır |
processing | Rotanın adımları çalışıyor; olası uyum kontrolü de buna dahil. | Hayır |
completed | Son adım tamamlandı: alıcıya ödendi. | Evet |
failed | Bir 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 |
refunded | Ayrılan tutar kullanılabilir bakiyenize döndü. | Evet |
cancelled | Bir ş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.
{
"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
accepteddurumuna geçer ve bakiyeniz karşılıyorsa hemen fonlanır. - Reddedildiğinde
cancelledolur;cancelledkaydınınbydeğeri reddeden kişidir. - Kimse onaylamadan teklifin süresi dolarsa ödeme
systemtarafı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 parametresi | Anlamı |
|---|---|
state | Yukarıdaki durumlardan biri. processing, rotası çalışan her ödemeyi listeler. |
limit | 1 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"