İçeriğe geç
Apex Settlement

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.

Shell
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"
200 OK
{
  "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"
200 OK
[
  {
    "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
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" }
  }'
201 Created
{
  "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.

201 Created
{
  "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_reasonNe yapmalı
beneficiary_not_verifiedAlıcının durumu verified olana kadar bekleyin.
onboarding_requiredHer rotadaki bir Provider hesabınızı henüz onaylamadı. Hesap ekibinize yazın.
funds_at_other_providerTutar 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_rangeTutar rotaların kabul ettiği aralığın dışında. Farklı bir tutar deneyin.
temporarily_unavailableRota bir süreliğine durdurulmuş. Daha sonra tekrar deneyin.
no_routeBu ö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..." }'
201 Created
{
  "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"
200 OK (kısaltılmış)
{
  "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.

Sonraki adımlar

Bu sayfada