دفع CIB/Edahabiya
قبول مدفوعات CIB/Edahabiya
قم بإنشاء معاملة دفع آمنة باستخدام بوابة CIB/Edahabiya للدفع الإلكتروني مع دعم التوقيع المشفر والتحقق من الأمان
نقطة النهاية API
GET
https://sofizpay.com/make-cib-transaction/مولد الرابط
عندما يكون keep_return_url = False، ستحصل على callback موقع مشفريًا للتحقق من صحة المعاملة
الرابط المُولد:
http
https://sofizpay.com/make-cib-transaction/?account=GDNS27ISCGOIJFXC6CM4O5SVHVJPSWR42QEBWUFF24N5VVHGW73ZSJNQ&amount=150.75&full_name=Ahmed+Ben+Ali&phone=%2B213555123456&email=ahmed.benali%40example.com&return_url=https%3A%2F%2Fmystore.com%2Fpayment-callback&webhook_url=https%3A%2F%2Fmystore.com%2Fapi%2Fcib-webhook&invoice_id=INV-2026-001&language=ar&memo=Order+%2312345&redirect=yes&keep_return_url=Trueمعاملات الطلب
| المعامل | النوع | مطلوب | الوصف |
|---|---|---|---|
account | string | مطلوب | حساب Sofizpay الخاص بك لاستقبال المدفوعات |
amount | number | مطلوب | مبلغ الدفعة بالدينار الجزائري |
full_name | string | مطلوب | الاسم الكامل للعميل |
phone | string | مطلوب | رقم الهاتف للعميل (يفضل بالتنسيق الدولي) |
email | string | مطلوب | عنوان البريد الإلكتروني للعميل |
return_url | string (URL) | اختياري | الرابط الذي سيتم إعادة التوجيه إليه بعد الدفع |
webhook_url | string (URL) | اختياري | عنوان URL اختياري (HTTP/HTTPS) لاستلام إشعارات التحديث التلقائية (Webhooks) |
invoice_id | string | اختياري | معرّف الفاتورة الاختياري لربط المعاملة بفاتورة سابقة |
language | string | اختياري | لغة واجهة بوابة CIB (الافتراضي 'ar') |
memo | string | اختياري | ملاحظة اختيارية للمعاملة (يتم اقتطاعها إلى 28 بايتاً) |
redirect | 'yes' | 'no' | مطلوب | ما إذا كان سيتم إعادة التوجيه التلقائي أم لا |
keep_return_url | 'True' | 'False' | اختياري | إذا كان True، سيتم توقيع callback وإعادة التوجيه مع رابط يحتوي على التوقيع المشفر |
استجابة ناجحة (200)
عند إنشاء المعاملة بنجاح
json
{
"success": true,
"transaction_id": "600aed3b-8dd2-490c-8e45-9b81267b1f2b",
"cib_transaction_id": "2517039448",
"payment_url": "https://cib.satim.dz/payment/merchants/SATIM/payment_ar.html?mdOrder=HNsBw1u4An3Q44BCJ7LI",
"amount": "150.75",
"status": "pending_user_transfer_start",
"more_info_url": "https://sofizpay.com/sep24/transaction/more_info?id=600aed3b-8dd2-490c-8e45-9b81267b1f2b",
"webhook_url": "https://mystore.com/api/cib-webhook",
"cib_response": {
"errorCode": "0",
"orderId": "isezBL9uLxWRBIBE56T7",
"formUrl": "https://cib.satim.dz/payment/merchants/SATIM/payment_ar.html?mdOrder=HNsBw1u4An3Q44BCJ7LI"
}
}استجابة خطأ (400)
عند وجود معاملات غير صحيحة أو مفقودة
json
{
"status": "error",
"message": "Invalid or missing parameters."
}إشعارات الـ Webhook والأحداث
قم بتمرير معامل webhook_url عند إنشاء المعاملة لاستلام إشعارات فورية ومباشرة (من خادم إلى خادم) بمجرد تحديث حالة المعاملة.
يجب أن يكون رابط الـ Webhook مستخدماً لبروتوكول HTTP أو HTTPS ويحتوي على نطاق صحيح.
عندما يتم إتمام أو رفض عملية الدفع عبر بوابة CIB/الذهبية، ترسل منصة SofizPay طلب HTTP POST إلى رابط الـ Webhook الخاص بك مع البيانات التالية:
cib.payment.updated (payment_status: "success")
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://your-domain.com/api/webhook/success1500005965287001",
18 "signature": "MEQCIFz8v982hfkjdsf983274hfkjsdf...=="
19}شرح حقول حمولة الـ Webhook
| المعامل | النوع | الوصف |
|---|---|---|
event | string | اسم الحدث، دائماً 'cib.payment.updated' |
payment_status | 'success' | 'failed' | حالة الدفع: 'success' للنجاح أو 'failed' للفشل |
transaction_id | string (UUID) | المعرّف الفريد للمعاملة لدى SofizPay (UUID) |
cib_transaction_id | string | رقم عملية CIB/الذهبية لدى البنك (SATIM) |
order_id | string | معرّف الطلب الخاص بـ SATIM |
order_number | number | رقم الطلب الرقمي لدى SATIM |
order_status | number | كود حالة الطلب لدى SATIM (مثال: 2 للعمليات المقبولة، 6 للمرفوضة) |
amount | number | المبلغ بالسنتيم (مثال: 150000 = 1500.00 دج) |
currency | string | رمز العملة الرقمي ISO 4217 (012 للدينار الجزائري) |
error_code | number | null | كود الخطأ من البنك في حال الفشل (أو null عند النجاح) |
error_message | string | null | رسالة توضيح الخطأ من البنك (أو null عند النجاح) |
action_code | number | null | كود إجراء البنك الداخلي (مثال: 116 لرصيد غير كافٍ) |
action_code_description | string | null | وصف كود الإجراء (مثال: 'Insufficient funds') |
resp_code | string | كود الاستجابة البنكية ('00' للقبول، '05' للرفض) |
resp_code_desc | string | وصف كود الاستجابة ('Approved' أو 'Declined') |
message | string (URL/text) | نص التحقق المجمّع المستخدم في فحص التوقيع الرقمي |
signature | string (Base64) | التوقيع الرقمي المشفر بصيغة Base64 للتحقق من أمان ومصدر البيانات |
CIB/Edahabiya Sandbox - توثيق بيئة الاختبار
CIB/Edahabiya Sandbox عبارة عن بيئة اختبار تحاكي بوابة دفع SATIM CIB/Edahabiya. وهي تسمح لمطوري الواجهة الأمامية باختبار تدفق معاملات إيداع CIB/Edahabiya بالكامل دون الاتصال بنظام دفع SATIM الحقيقي.
لعرض معاملات بيئة الاختبار (Sandbox) في تطبيق SofizPay، يجب عليك أولاً تفعيل 'وضع الاختبار' (Testing Mode) من إعدادات التطبيق.
CIB/Edahabiya Sandbox - توثيق بيئة الاختبار - 1. إنشاء معاملة CIB/Edahabiya
GET
GET sofizpay.com/make-cib-transaction/إنشاء معاملة إيداع CIB/Edahabiya وهمية وإرجاع رابط الدفع.
بطاقات الاختبار
| رقم البطاقة | تاريخ الانتهاء | CVV | النتيجة |
|---|---|---|---|
6280581001234567 | 12/28 | 123 | تمت الموافقة |
6280581009876543 | 12/29 | 456 | تمت الموافقة |
استخدام أي رمز OTP غير 123456 سيؤدي لخطأ "Invalid OTP code" بغض النظر عن البطاقة المستخدمة.
أفضل الممارسات الأمنية
استخدم HTTPS لروابط الإرجاع
أضف معامل order_id داخلي في رابط الإرجاع (مثال: ?order_id=12345) لتسهيل التتبع والتسوية
عند استلام الـ callback، احفظ cib_transaction_id مع order_id الداخلي الخاص بك في قاعدة البيانات
بعد الحفظ، استرجع cib_transaction_id باستخدام order_id الداخلي، ثم تحقق من حالة المعاملة عن طريق استدعاء نقطة نهاية فحص معاملة CIB/Edahabiya مع ذلك cib_transaction_id