Hızlı başlangıç
API anahtarından tamamlanmış bir ödemeye, ilk sandbox ödemenizi gönderin.
Bu rehber, sandbox bakiyenizden Almanya'daki bir şirkete 1000 USDC gönderir; şirkete 918.58 EUR ulaşır. Altı çağrı yeterli. Durumu (standing) active olan bir sandbox hesabına ve bu hesapta yönetici rolüne sahip bir kişiye ihtiyacınız var.
Önce iki ortam değişkeni tanımlayın. Sandbox temel URL'si hesabınızla birlikte gelir.
export APEX_BASE_URL="<your sandbox base URL>"
export APEX_API_KEY="ak_test_..."Test anahtarı alın
Müşteri panelinde API anahtarları sayfasını açın ve Anahtar oluştur'u seçin. Anahtara Quickstart gibi bir ad ve şu izinleri verin:
- Bakiyeleri, ödemeleri ve alıcıları okuma (
customer:read) - Ödeme oluşturma ve iptal etme (
customer:payouts:create) - Alıcı kaydetme (
customer:beneficiaries:write)
Anahtar yalnızca bir kez gösterilir: ak_test_ ve ardından iki rastgele bölüm. Gizli değer deponuzda saklayın, sonra çalıştığını doğrulayın:
curl "$APEX_BASE_URL/v1/customer" \
-H "Authorization: Bearer $APEX_API_KEY"{
"id": "5f8c2a91-3e4b-4d6a-9c1f-7b2e8d4a6c30",
"legal_name": "Tom Trading Inc",
"type": "business",
"country": "US",
"standing": "active",
"providers": ["bvnk", "zerohash"],
"kind": "direct"
}providers, hesabınızı onaylamış Provider'ları listeler. Bir rota yalnızca bu Provider'ları kullanabilir.
Bakiyenizi kontrol edin
curl "$APEX_BASE_URL/v1/balances" \
-H "Authorization: Bearer $APEX_API_KEY"[
{
"asset": "USDC",
"available": "1000",
"held": "0",
"held_at": [{ "provider": "bvnk", "available": "1000", "held": "0" }]
}
]available şu anda gönderebileceğiniz kullanılabilir tutardır. held, yoldaki ödemeler için ayrılan tutardır. held_at her bakiyeyi onu tutan Provider'a göre ayırır. Bir ödeme yalnızca tek bir Provider'daki kısımdan gönderilir; bu yüzden size hangi rotaların sunulacağını paranızın nerede olduğu belirler. Ayrıntılar için Bakiyeler ve para yatırma.
Sandbox bakiyenizi fonlamak
GET /v1/deposit-instructions?asset=USDC paranın nereye yatırılacağını söyler. Sandbox'ta Provider'lar simüle edilir ve adresler yer tutucudur; bunlara gönderilen hiçbir şey ulaşmaz. Sandbox bakiyenize test tutarı eklenmesi için hesap ekibinize yazın.
Bir alıcı oluşturun ya da seçin
Kayıtlı alıcılarınızı listeleyin ve göndermek istediğiniz ülke ile para birimine sahip, durumu (state) verified olan birini seçin:
curl "$APEX_BASE_URL/v1/beneficiaries" \
-H "Authorization: Bearer $APEX_API_KEY"Ya da yeni bir alıcı kaydedin. Almanya'da euro ile ödenen bir şirket için details içinde iban ve name gerekir:
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": "Muster GmbH",
"country": "DE",
"asset": "EUR",
"details": { "iban": "DE89370400440532013000", "name": "Muster GmbH" }
}'{
"id": "c1e7b3a9-4d2f-4a6e-8b05-9f3d2c7e1a84",
"kind": "external",
"state": "pending_verification",
"party_type": "business",
"name": "Muster GmbH",
"country": "DE",
"asset": "EUR",
"details": { "iban": "••••3000", "name": "Muster GmbH" },
"available": true,
"created_at": "2026-11-12T09:41:07Z",
"updated_at": "2026-11-12T09:41:07Z"
}Bir hedefin istediği hesap bilgileri ülkeyi ve para birimini izler: SEPA ülkesinde euro için iban ve name, GB'de sterlin için account_number, sort_code ve name, ABD'de dolar için account_number, routing_number ve name. O hedefe giden hiçbir rotanın istemediği bir alan beneficiary_fields_invalid ile reddedilir. Hesap numaraları yanıtta yalnızca son dört karakteriyle görünür. Tüm alıcı türleri ve hedefler için Alıcılar.
Yeni alıcılar incelemeyi bekler
Kaydettiğiniz alıcı pending_verification (Doğrulanıyor) durumunda başlar. Uyum ekibimiz onu sandbox'ta da doğrular; durumu verified olduğunda ödeme yapabilirsiniz. Doğrulandığı anda haberdar olmak için beneficiary.updated olayına abone olun.
Teklif isteyin
Tutarı, bakiyenizden çıkacağı varlığı, alıcıyı ve ödemenin amacını gönderin. Hedef ülke ve para birimi alıcınınkidir; bunları göndermezsiniz.
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": "c1e7b3a9-4d2f-4a6e-8b05-9f3d2c7e1a84",
"purpose": "services",
"preference": "fastest"
}'Alan
Tür
Sandbox, bir Alman IBAN'ına iki rota sunar: SEPA Instant ve SEPA Credit Transfer. İkisi de 918.58 EUR ulaştırır; SEPA Credit Transfer yaklaşık bir gün daha uzun sürer. Aşağıdaki yanıt ilk teklife kısaltılmıştır.
{
"quote_set_id": "6e2a9c4f-8b1d-4f37-a5c2-1d9e7b3f0a52",
"quotes": [
{
"quote_id": "qt1.eyJkIjoiNmUyYTljNGYtOGIxZC00ZjM3...",
"send": { "amount": "1000", "asset": "USDC" },
"receive": { "amount": "918.58", "asset": "EUR" },
"fees": [
{ "provider": "bvnk", "component": "provider", "amount": { "amount": "1", "asset": "USDC" } },
{ "provider": "bvnk", "component": "provider", "amount": { "amount": "0.5", "asset": "EUR" } }
],
"rates": [
{ "provider": "bvnk", "rate": "0.92" },
{ "provider": "bvnk", "rate": "1" }
],
"providers": ["bvnk"],
"settlement_seconds": 120,
"estimated_arrival": "2026-11-12T10:02:00Z",
"expires_at": "2026-11-12T10:01:00Z",
"labels": ["fastest"]
}
],
"server_time": "2026-11-12T10:00:00Z"
}Rakamları adım adım okuyun: dönüşüm 1 USDC ücret alır, kalan 999 USDC 0.92 kurundan 919.08 EUR'ya çevrilir, SEPA Instant ödemesi de 0.5 EUR alır. Alıcıya 918.58 EUR ulaşır. Her ücret, o adımın aldığı varlıktadır. Fiyatlandırmanız bizim ücretimizi içeriyorsa bir service_fee (hizmet ücreti) satırı da görünür.
labels, en çok ulaştıran teklifi (cheapest, panelde "En çok ulaşan") ve en erken tamamlananı (fastest) işaretler. Bir teklif expires_at zamanına kadar geçerlidir; sandbox'ta bu yaklaşık bir dakikadır. Kalan süreyi kendi saatinizden değil server_time değerinden sayın.
Hiç teklif sunulamadığında çağrı yine 201 döner; quotes listesi boştur ve bir unavailable_reason gelir:
unavailable_reason | Ne yapmalı |
|---|---|
beneficiary_not_verified | Alıcının durumu verified olana kadar bekleyin. |
onboarding_required | Her rotadaki bir Provider hesabınızı henüz onaylamadı. Hesap ekibinize yazın. |
funds_at_other_provider | Tutar sizde var, ancak rotaların başladığı Provider'da değil. deposit_at içinde listelenen bir Provider'a yatırın. |
amount_out_of_range | Tutar rotaların kabul ettiği aralığın dışında. Farklı bir tutar deneyin. |
temporarily_unavailable | Rota bir süreliğine durdurulmuş. Daha sonra tekrar deneyin. |
no_route | Bu ödemeyi taşıyabilecek bir rota yok. |
Teklifi kabul edin
Teklifin süresi dolmadan quote_id ile bir ödeme oluşturun. Idempotency-Key başlığını gönderin: bu ödeme için bir kez ürettiğiniz ve her yeniden denemede değiştirmeden tekrar gönderdiğiniz bir değer. Bkz. Idempotency.
curl -X POST "$APEX_BASE_URL/v1/payouts" \
-H "Authorization: Bearer $APEX_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3f6c1d2e-8a4b-4c9d-b1e7-5a2f9c8d0e13" \
-d '{ "quote_id": "qt1.eyJkIjoiNmUyYTljNGYtOGIxZC00ZjM3..." }'{
"id": "7d41f0b2-9c3e-4a85-b6d1-2e8f5a7c9b13",
"state": "processing",
"send": { "amount": "1000", "asset": "USDC" },
"receive": { "amount": "918.58", "asset": "EUR" },
"fees": [
{ "provider": "bvnk", "component": "provider", "amount": { "amount": "1", "asset": "USDC" } },
{ "provider": "bvnk", "component": "provider", "amount": { "amount": "0.5", "asset": "EUR" } }
],
"rates": [
{ "provider": "bvnk", "rate": "0.92" },
{ "provider": "bvnk", "rate": "1" }
],
"beneficiary": {
"id": "c1e7b3a9-4d2f-4a6e-8b05-9f3d2c7e1a84",
"name": "Muster GmbH",
"country": "DE",
"party_type": "business"
},
"delivered_to": "bank_account",
"legs": [
{ "index": 0, "provider": "bvnk", "from": "USDC", "to": "EUR", "state": "pending" },
{ "index": 1, "provider": "bvnk", "from": "EUR", "to": "EUR", "state": "pending" }
],
"initiated_by": { "actor": "customer", "kind": "api_key", "id": "a3d9e1f4-6b2c-4e8a-9f17-2c5b8d1e4a60" },
"initiated_by_you": true,
"cancellable": false,
"created_at": "2026-11-12T10:00:20Z",
"updated_at": "2026-11-12T10:00:20Z"
}Yeni ödemenin state alanı şunlardan biridir:
processing(İşleniyor): bakiyeniz yetti, tutar ayrıldı ve rota yürütülüyor.awaiting_approval(Onay bekliyor): onay kurallarınız ödemeyi ikinci bir kişi için bekletiyor; o kişi müşteri panelinden onaylar. Bir API anahtarı hiçbir zaman onay vermez.accepted(Kabul edildi): rotanın ilk Provider'ındaki bakiyeniz henüz yetmiyor. Ödeme para bekler; teklifin süresi önce dolarsa iptal edilir. Bu yüzden göndermeden önce bakiyenizi fonlayın.
Bir teklif yalnızca bir ödemeye dönüşür. Aynı teklifi farklı bir Idempotency-Key ile yeniden kabul etmek quote_already_used (409) döner. Bir ödeme fonlanana kadar (accepted ya da awaiting_approval durumundayken) POST /v1/payouts/{id}/cancel ile iptal edebilirsiniz.
Ödemeyi sonuna kadar izleyin
Webhook ile (önerilen). payout.updated için bir uç nokta kaydedin; her durum değişikliğinde ödemenin tamamını size göndeririz. Bkz. Webhook'lar.
Yoklayarak (polling). Ödemeyi son durumlarından birine ulaşana kadar okuyun. En fazla birkaç saniyede bir sorgulayın ve aralığı zamanla açın.
curl "$APEX_BASE_URL/v1/payouts/7d41f0b2-9c3e-4a85-b6d1-2e8f5a7c9b13" \
-H "Authorization: Bearer $APEX_API_KEY"{
"id": "7d41f0b2-9c3e-4a85-b6d1-2e8f5a7c9b13",
"state": "completed",
"receive": { "amount": "918.58", "asset": "EUR" },
"legs": [
{ "index": 0, "provider": "bvnk", "from": "USDC", "to": "EUR", "state": "completed", "settled_at": "2026-11-12T10:01:04Z" },
{ "index": 1, "provider": "bvnk", "from": "EUR", "to": "EUR", "state": "completed", "settled_at": "2026-11-12T10:02:11Z" }
],
"timeline": [
{ "state": "accepted", "at": "2026-11-12T10:00:20Z", "by": { "actor": "customer", "kind": "api_key", "id": "a3d9e1f4-6b2c-4e8a-9f17-2c5b8d1e4a60" } },
{ "state": "funded", "at": "2026-11-12T10:00:20Z", "by": { "actor": "customer", "kind": "api_key", "id": "a3d9e1f4-6b2c-4e8a-9f17-2c5b8d1e4a60" } },
{ "state": "processing", "at": "2026-11-12T10:00:20Z", "by": { "actor": "customer", "kind": "api_key", "id": "a3d9e1f4-6b2c-4e8a-9f17-2c5b8d1e4a60" } },
{ "state": "completed", "at": "2026-11-12T10:02:11Z", "by": { "actor": "system" } }
]
}completed (Tamamlandı), refunded (İade edildi) ve cancelled (İptal edildi) son durumlardır. failed (Başarısız) ise son değildir: operasyon ekibimiz ya başarısız adımı yeniden dener ve ödeme processing durumuna döner, ya da tutarı bakiyenize iade eder (refunded). Başarısız bir ödemede failure alanı bulunur; hangi adımın tamamlanamadığını ve bir kodu gösterir.