إشعارات الـ Webhooks اللحظية
توثيق إشعارات الـ Webhooks والتحقق الرقمي
تتيح لك بوابة SofizPay استقبال إشعارات خادم إلى خادم (Server-to-Server) فور إتمام أو رفض معاملة CIB والبطاقة الذهبية، مع توقيع رقمي مشفر RSA SHA-256 لحماية عمليات الدفع بنسبة 100%.
حدث الدفع الرسمي: cib.payment.updated
يتم إرسال هذا الإشعار تلقائياً عبر طلب HTTP POST بترميز JSON إلى عنوان webhook_url المحدد عند إنشاء معاملة CIB/الذهبية.
نموذج إشعار نجاح الدفع (Approved)
يصل هذا الإشعار عندما يقوم العميل بتأكيد الدفع وإدخال رمز OTP الصحيح.
json
1{
2 "event": "cib.payment.updated",
3 "payment_status": "success",
4 "transaction_id": "bb979126-4e55-49dd-8ecc-a1d59867d2b0",
5 "cib_transaction_id": "5965287001",
6 "order_id": "satim_order_a1b2c3d4",
7 "order_number": 5965287001,
8 "order_status": 2,
9 "amount": 150000,
10 "currency": "012",
11 "error_code": null,
12 "error_message": null,
13 "action_code": null,
14 "action_code_description": null,
15 "resp_code": "00",
16 "resp_code_desc": "Approved",
17 "message": "https://yourstore.com/api/cib-webhook/success1500005965287001",
18 "signature": "MEQCIFz8v982hfkjdsf983274hfkjsdf98234kjhsdf...=="
19}نموذج إشعار فشل/رفض الدفع (Declined)
يصل عندما يُرفض الدفع بسبب رصيد غير كافٍ أو بطاقة منتهية أو رمز OTP خاطئ.
json
1{
2 "event": "cib.payment.updated",
3 "payment_status": "failed",
4 "transaction_id": "bb979126-4e55-49dd-8ecc-a1d59867d2b0",
5 "cib_transaction_id": "5965287001",
6 "order_id": "satim_order_a1b2c3d4",
7 "order_number": 5965287001,
8 "order_status": 6,
9 "amount": 150000,
10 "currency": "012",
11 "error_code": 5,
12 "error_message": "Transaction declined by issuer",
13 "action_code": 116,
14 "action_code_description": "Insufficient funds",
15 "resp_code": "05",
16 "resp_code_desc": "Declined",
17 "message": "https://yourstore.com/api/cib-webhook/failed1500005965287001",
18 "signature": "MEYCIQDdr7234kjhsdf98234kjhsdf89234kjhsdf...=="
19}جدول تفاصيل حقول الـ Webhook
| الحقل | النوع | الوصف والاستخدام |
|---|---|---|
| event | string | معرف الحدث الرسمي، قيمته دائماً "cib.payment.updated" |
| payment_status | 'success' | 'failed' | حالة الدفع النهائية (success أو failed) |
| transaction_id | string (UUID) | المعرف الفريد للمعاملة لدى SofizPay |
| cib_transaction_id | string | رقم طلب SATIM / CIB المسجل لدى البنك |
| order_number | number | الرقم التسلسلي العددي للطلب في بوابة SATIM |
| order_status | number | رمز حالة الطلب (2: معتمد وناجح، 6: مرفوض، 3: ملغى أو منتهي المهلة) |
| amount | number (centimes) | المبلغ بالسنتيم الجزائري (مثلاً 150000 تعني 1500.00 دج) |
| currency | string | رمز العملة الرقمي ISO 4217 ("012" للدينار الجزائري DZD) |
| resp_code | string | رمز الاستجابة البنكي ("00" للعمليات المعتمدة) |
| resp_code_desc | string | وصف حالة الاستجابة ("Approved" أو "Declined") |
| message | string | النص الأصلي الموقع رقمياً والمستخدم في التحقق من التوقيع |
| signature | string (Base64) | التوقيع الرقمي RSA SHA-256 الصادر من SofizPay |