وثائق API

01

بيانات الاعتماد

في لوحتك ثلاث قيم: رقم حساب من 6 خانات، و ⁦API key⁩، و ⁦secret key⁩. يُعرض الـ ⁦secret key⁩ مرة واحدة فقط لحظة إنشائه؛ وإذا فقدته تُنشئ واحدًا جديدًا ويُلغى القديم في الخطوة نفسها. رقم الحساب وحده لا يمنح أي صلاحية — صحة كل طلب تأتي من التوقيع.

02

التوقيع

يُوقَّع كل طلب بخوارزمية ⁦HMAC-SHA256⁩. وفي الطلبات بلا جسم يُستخدم ⁦sha256("")⁩.

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

⁦path⁩ هو المسار الكامل بصيغة ⁦/api/v1/...⁩ ولا يتضمن سلسلة الاستعلام. وإذا خرج الطابع الزمني عن ±300 ثانية من وقت الخادم يُرفض الطلب.

الترويسات الإلزامية

03

إنشاء عملية دفع

⁦odeme_adresi⁩ في الاستجابة هو العنوان الذي توجّه إليه عميلك.

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

عدد صحيح بوحدة الكُروش (الوحدة الصغرى). إلزامي.

magaza_adi

الاسم الذي يظهر على شاشة الدفع. اختياري.

magaza_referansi

مرجع طلبك الخاص؛ فريد داخل حسابك. اختياري.

bildirim_adresi

عنوان ⁦https⁩ تُرسَل إليه النتيجة. اختياري.

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⁩

إلزامي عند إنشاء عملية دفع. الطلب الثاني بالمفتاح نفسه لا ينشئ عملية دفع ثانية؛ بل يعيد الاستجابة الأولى نفسها برمز ⁦200⁩. أما المفتاح نفسه مع جسم مختلف فيعيد ⁦409 (9000010)⁩.

شاشة الدفع

يصل عميلك إلى شاشة الدفع لدينا عبر ⁦odeme_adresi⁩. المبلغ ثابت ولا يمكن تغييره؛ ولا يظهر على الشاشة سوى المبلغ واسم المتجر. تُدخَل بيانات البطاقة لدينا مباشرة، ويكتمل ⁦3D Secure⁩ من جانبنا.

الاستعلام عن الحالة

⁦durum⁩ واحدة من ثلاث قيم: ⁦olusturuldu · odendi · suresi_doldu⁩. وإذا فاتك الإشعار فيمكنك دائمًا قراءة النتيجة النهائية من هنا — الإشعار ليس الدليل الوحيد.

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

إشعار النتيجة

إذا زوّدتنا بـ ⁦bildirim_adresi⁩ فستستقبل طلب ⁦POST⁩ موقَّعًا عند اكتمال الدفع. والتوقيع يتبع المعادلة نفسها التي توقّع بها طلباتك؛ ويُستخدم مسار عنوانك أنت بوصفه ⁦path⁩.

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", ... }

معيار النجاح هو استجابة ⁦2xx⁩. وتُعاد المحاولات الفاشلة بعد 1 د · 5 د · 15 د · 1 س · 6 س · 24 س. ولا تتغير ⁦X-CAV-Delivery⁩ بين المحاولات: استخدم هذه القيمة لديك حتى لا تعالج الإشعار نفسه مرتين.

05

رموز الأخطاء

تُعاد الأخطاء بجسم ⁦RFC 7807 (application/problem+json)⁩؛ وحقل ⁦code⁩ نص من 7 خانات.