API Docs

01

Kimlik bilgileri

Panelinizde üç değer vardır: 6 haneli hesap numarası, API anahtarı ve gizli anahtar. Gizli anahtar yalnız üretildiği anda bir kez gösterilir; kaybederseniz yenisini üretirsiniz ve eskisi aynı anda geçersiz olur. Hesap numarası tek başına yetki vermez — her isteğin geçerliliği imzadan gelir.

02

İmzalama

Her istek HMAC-SHA256 ile imzalanır. Gövdesiz isteklerde sha256("") kullanılır.

canonical = timestamp + "\n" + METHOD + "\n" + path + "\n" + sha256(body)
signature = hex( hmac_sha256(canonical, gizli_anahtar) )

path, /api/v1/... biçiminde tam yoldur ve sorgu dizesi içermez. Zaman damgası sunucu saatine göre ±300 saniye dışındaysa istek reddedilir.

Zorunlu başlıklar

03

Ödeme oluşturma

Yanıttaki odeme_adresi müşterinizi yönlendireceğiniz adrestir.

POST /api/v1/odeme

{
  "tutar_minor": 150000,
  "magaza_adi": "Örnek Mağaza",
  "magaza_referansi": "SIP-2026-0001",
  "bildirim_adresi": "https://magaza.example.com/cav-bildirim"
}

tutar_minor

Kuruş cinsinden tam sayı. Zorunlu.

magaza_adi

Ödeme ekranında görünecek ad. İsteğe bağlı.

magaza_referansi

Kendi sipariş referansınız; hesabınızda tekildir. İsteğe bağlı.

bildirim_adresi

Sonucun gönderileceği https adresi. İsteğe bağlı.

201 Created

{
  "kod": "k7m2xq9p",
  "magaza_referansi": "SIP-2026-0001",
  "durum": "olusturuldu",
  "tutar_minor": 150000,
  "para_birimi": "TRY",
  "odeme_adresi": "https://cryptoavans.com/l/k7m2xq9p",
  "olusturuldu_at": "2026-09-08T09:00:00.000Z",
  "gecerlilik_bitisi_at": "2026-09-08T10:00:00.000Z",
  "odendi_at": null
}

Idempotency-Key

Ödeme oluşturmada zorunludur. Aynı anahtarla gönderilen ikinci istek ikinci ödeme oluşturmaz; ilk yanıtın aynısını 200 ile döner. Aynı anahtar farklı bir gövdeyle gelirse 409 (9000010) alırsınız.

Ödeme ekranı

Müşteriniz odeme_adresi üzerinden bizim ödeme ekranımıza gelir. Tutar sabittir ve değiştirilemez; ekranda yalnız tutar ve mağaza adı görünür. Kart bilgisi doğrudan bize girilir, 3D Secure bizim tarafımızda tamamlanır.

Durum sorgusu

durum üç değerden biridir: olusturuldu · odendi · suresi_doldu. Bildirimi kaçırdıysanız nihai sonucu her zaman buradan okuyabilirsiniz — bildirim tek kanıt değildir.

GET /api/v1/odeme/k7m2xq9p

200 OK
{ "kod": "k7m2xq9p", "durum": "odendi", "tutar_minor": 150000,
  "para_birimi": "TRY", "odendi_at": "2026-09-08T09:12:31.442Z", ... }

04

Sonuç bildirimi

bildirim_adresi verdiyseniz ödeme tamamlandığında imzalı bir POST alırsınız. İmza, isteklerinizi imzaladığınız formülün aynısıdır; path olarak kendi adresinizin yolu kullanılır.

POST <bildirim_adresi>
X-CAV-Event: odeme.tamamlandi
X-CAV-Delivery: 3f1a...
X-CAV-Timestamp: 1788000000
X-CAV-Signature: <hex>

{ "olay": "odeme.tamamlandi", "kod": "k7m2xq9p",
  "magaza_referansi": "SIP-2026-0001", "durum": "odendi",
  "tutar_minor": 150000, "para_birimi": "TRY",
  "odendi_at": "2026-09-08T09:12:31.442Z", ... }

Başarı ölçütü 2xx yanıtıdır. Başarısız denemeler 1 dk · 5 dk · 15 dk · 1 sa · 6 sa · 24 sa aralıklarıyla tekrarlanır. X-CAV-Delivery denemeler arasında değişmez: kendi tarafınızda bu değeri kullanarak aynı bildirimi iki kez işlemekten kaçının.

05

Hata kodları

Hatalar RFC 7807 (application/problem+json) gövdesiyle döner; code alanı 7 haneli bir metindir.