توثيق تكامل المتجر

منصة وسيط دفع — API الإصدار v1

← صفحة الدفع

فكرة المنصة

المنصة ليست متجراً؛ هي وسيط دفع. يُنشئ مسؤول المنصة مفتاح API لكل متجر من لوحة الأدمن. المتجر يطلب إنشاء جلسة دفع عبر الـ API، ثم يوجّه العميل إلى payment_url على هذه المنصة. بعد نجاح أو فشل الدفع، تُرسل المنصة نتيجةً إلى callback_url (إن حددته) عبر POST مع JSON وحقل signature للتحقق.

المصادقة

أرسل المفتاح في الترويسة:

X-API-Key: pk_your_key_here

في بيئة الإنتاج استخدم الترويسة فقط. لا تضع المفتاح في سلسلة الاستعلام (query) — قد يظهر في السجلات أو الـ Referer.

نقطة الصحة

GET https://injezha.com/api/v1/status

إنشاء جلسة دفع

POST https://injezha.com/api/v1/sessions
Content-Type: application/json
X-API-Key: pk_...

{
  "amount": 10.50,
  "description": "طلب #123",
  "external_reference": "ORD-123",
  "customer_email": "user@example.com",
  "metadata": { "product_id": 1 },
  "callback_url": "https://yourstore.com/payments/callback",
  "success_redirect_url": "https://yourstore.com/thanks",
  "cancel_redirect_url": "https://yourstore.com/cart"
}

amount إلزامي (USD). البقية اختيارية.

الاستجابة 201: token, payment_url, expires_at, وsession.

حالة الجلسة / إلغاء

GET https://injezha.com/api/v1/sessions/{token}
DELETE https://injezha.com/api/v1/sessions/{token}

قائمة المدفوعات للمفتاح

GET https://injezha.com/api/v1/payments

Callback بعد الدفع

عند وجود callback_url، تُرسل المنصة POST بصيغة JSON. الحقل event يكون payment.success أو payment.failed حسب status في سجل الدفع.

حقول تقريبية: session_token, external_reference, payment_id, status, amount, total_amount, currency, payment_method, transaction_id, metadata, paid_at, signature.

التحقق من التوقيع

  1. انسخ الـ JSON كاملاً وأزل الحقل signature.
  2. رتّب المفاتيح على المستوى الأعلى أبجدياً (ksort في PHP).
  3. احسب json_encode للمصفوفة الناتجة (بدون مسافات زائدة حسب تسلسل المفاتيح بعد ksort).
  4. hash_hmac('sha256', $json, $sessionToken . $salt) حيث $salt هي قيمة API_KEY_SALT في إعدادات المنصة (نفس سرّ التكامل لدى الطرفين عملياً).

مثال cURL

curl -X POST "https://injezha.com/api/v1/sessions" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_your_key_here" \
  -d '{"amount":25,"description":"Test","callback_url":"https://example.com/hook"}'