واجهة REST للاستخلاص في المغرب بالبطاقة أو نقدًا في الوكالة: عنوان أساسي واحد، ومفتاح يختار البيئة، وIdempotency، وأخطاء صريحة، وويب هوك موقّع. يُفتح وضع الاختبار بمجرد تسجيلكم — مجانًا، وبلا حد زمني، ودون موافقة تنتظرونها: تبدؤون الإدماج اليوم، دون انتظار أحد.
تتقاسم السندبوكس والإنتاج العنوان نفسه: https://api-psp.charipay.ma. المفتاح المُرسَل في الترويسة X-CHARI-PAY-API-KEY هو الذي يحسم: chari_sk_test_… يعمل على بيانات الاختبار، وchari_sk_live_… على البيانات الحقيقية، دون OAuth ولا رمز يحتاج إلى تجديد. وما دام الإنتاج غير مفعَّل، يتلقى مفتاح الإنتاج الرد 403 PRODUCTION_ACCESS_NOT_ENABLED. ويوم الانتقال، تغيّرون المفتاح وسرّ الويب هوك، لا شيفرتكم.
لا ينبغي أن يؤدي عطل في الشبكة إلى اقتطاع مرتين. الترويسة Idempotency-Key تغطي إعادة الإرسال التقنية للطلب نفسه؛ والحقل externalId، الفريد لكل حساب ولكل بيئة، يغطي إعادة الإصدار على مستوى النشاط: إذا كان الكائن موجودًا، تعيده الواجهة بالرمز 200 بدل إنشائه بالرمز 201. وتتبع عمليات الاسترداد المنطق نفسه بمرجع refundReference ثابت: 202 عند الإنشاء و200 عند الإعادة. احتفظوا بقيم Idempotency-Key مختلفة بين السندبوكس والإنتاج.
غلاف موحّد، { "error": { "code", "message" }, "correlationId" }، ورمز آلي ثابت: اختبروا الرمز، لا الرسالة أبدًا. يرافق correlationId كل استجابة، نجاحًا كانت أم خطأ؛ أرسلوا X-Request-Id فيصبح هو correlationId، لتتبّع النداء من بدايته إلى نهايته. ورموز HTTP تقول الباقي: 400 و401 و403 و404 و409 و410 و422 و429.
النقاط المكشوفة للعموم تعلن X-RateLimit-Limit وRemaining وReset، وتردّ بالرمز 429 مع Retry-After عند التجاوز. المبالغ بالدرهم وبالوحدة الكاملة (149.90 = 149,90 درهمًا)، والطوابع الزمنية بصيغة ISO-8601 وبتوقيت UTC؛ وتُقسَّم القوائم إلى صفحات عبر page وsize، وبالمؤشر (cursor) في المعاملات. وكل عنوان تصرّحون به يجب أن يكون HTTPS.
مفتاح لكل شركة ولكل بيئة، وصلاحيات (scopes) لكل وحدة: لا ينال كل مفتاح إلا ما يحتاجه. تنشئونه بأنفسكم من البوابة بعد إعادة المصادقة؛ ولا يُعرض المفتاح الكامل إلا مرة واحدة، ولا يُرسَل أبدًا بالبريد الإلكتروني. ويمكن أن يتعايش مفتاحان أثناء التدوير، دون انقطاع.
يحمل كل حدث الترويسة X-CHARI-SIGNATURE، وهي HMAC-SHA256 محسوب على الطابع الزمني والمحتوى الخام، والترويسة X-CHARI-TIMESTAMP بالميلي ثانية: قارنوا في زمن ثابت وارفضوا كل فارق يتجاوز خمس دقائق. أزيلوا التكرار عبر Chari-Event-Id، الثابت من محاولة إلى أخرى: التسليم مضمون مرة واحدة على الأقل، لا بالترتيب بالضرورة. وأسرار التوقيع مختلفة بين السندبوكس والإنتاج.
كل شيء يُضبط من البوابة دون المرور بنا: تنشئون مفاتيح الاختبار وتختارون صلاحياتها، وتصرّحون بعناوين الاستقبال وبلائحة الأحداث التي يتلقاها كل عنوان، وترسلون حدثًا تجريبيًا، ثم تعيدون قراءة كل تسليم مع الرمز الذي ردّ به خادمكم. ويُعاد التسليم الفاشل بنقرة واحدة، والمصادقة الثنائية (TOTP) متاحة لحماية الدخول.
تحققوا من التوقيع قبل قراءة المحتوى، وأزيلوا التكرار عبر معرّف الحدث، وأجيبوا بـ 2xx بمجرد تسجيل الحدث: المنصة تتكفل بالباقي. إن لم يصلها 2xx، تعيد المحاولة فورًا، ثم بعد دقيقة و5 دقائق و30 دقيقة وساعة، ثم كل 6 ساعات، حتى 16 محاولة على مدى نحو 72 ساعة؛ وبعدها يُعتبر التسليم فاشلًا ويُعاد من البوابة. عشرون حدثًا موثَّقة — المدفوعات، والاشتراكات، والاسترداد، وحركات حساب الأداء، والتوزيع — وتختارون ما يتلقاه كل عنوان استقبال. وأثناء تدوير السرّ، تحمل الترويسة X-CHARI-SIGNATURE-NEXT التوقيع المحسوب بالسرّ الجديد.
// En-têtes reçusX-CHARI-SIGNATURE: a3f19c… (HMAC-SHA256)X-CHARI-TIMESTAMP: 1756166400000Chari-Event-Id: 9f2c31a4-…Chari-Event-Type: payment.succeeded // Corps — signé tel quel, octet par octet{ … }وضع الاختبار بيئة كاملة — مفاتيح API، وروابط الدفع، وجلسات الدفع، والاشتراكات، والاسترداد، والويب هوك — تُفتح بمجرد تسجيلكم. ثلاثة حقول (الاسم، والبريد الإلكتروني المهني، والشركة)، ورابط تفعيل يصلكم بالبريد الإلكتروني، ثم اختيار كلمة المرور: أنتم في البوابة، وفيها تنشئون مفتاح الاختبار بأنفسكم. أدّوا بعد ذلك ببطاقة الاختبار 4918 9141 0719 5005، والرمز CVV 123، وأي تاريخ انتهاء مستقبلي، ورمز 3-D Secure 555: ترون مسار زبونكم وتتلقون الويب هوك payment.succeeded. هذه البطاقة وحدها مقبولة في السندبوكس، ولا يتحرك أي مال حقيقي. كل ذلك مجاني، بلا حد زمني، دون بطاقة بنكية ولا التزام، ودون أي موافقة تنتظرونها: التحقق من شركتكم (KYB) يجري بالتوازي، ولا يشترطه إلا الانتقال إلى الإنتاج. والخطوات الثماني للتسجيل موثّقة أيضًا كنداءات API، لمن يريد أتمتة كل شيء.
المرجع الكامل — 13 وحدة و58 نقطة نهاية، مع أمثلة curl وJavaScript وPython وPHP — منشور على هذا الموقع، متاح للجميع دون حساب. وهو مُولَّد من مواصفة OpenAPI للواجهة، ويمكن تنزيل مجموعة Postman والمواصفة، وكذلك حزمة لمساعدي البرمجة — ملف Markdown لكل وحدة، والأدلة، وبطاقة الاختبار، والمواصفة.
تسجيل في البوابة، وتفعيل بالبريد الإلكتروني، واختيار كلمة المرور: يُنشأ مفتاح الاختبار من فضاء المطوّرين ولا يُعرض إلا مرة واحدة. لا شيء تدفعونه، ولا شيء توقّعونه، ولا وثيقة تقدّمونها في هذه المرحلة.
روابط الدفع، وصفحة الدفع المستضافة، والاشتراكات، والاسترداد، والويب هوك: كل شيء يعمل في السندبوكس ببطاقة الاختبار. وبالنسبة إلى الاشتراك، يفتح تاريخُ بدايةٍ في اليوم نفسه الاستحقاق الأول فورًا، وتجلب الدورية اليومية الاستحقاق الموالي من الغد. وتُرسَل الويب هوك بشكل عادي في السندبوكس: تحققوا من التوقيع وإزالة التكرار والردود 2xx قبل يوم الانتقال.
حين تكونون جاهزين: تحقق KYB (وثائق الهوية والسجل التجاري، مع موافقة بشرية مزدوجة)، ثم عرض مسعَّر، ثم رسوم تفعيل 6 000 درهم شاملة الضريبة تُؤدّى مرة واحدة، ثم التفعيل. تستبدلون مفتاح الاختبار بمفتاح الإنتاج، ومعه سرّ الويب هوك: وباقي شيفرتكم لا يتغير.
أنشئوا حساب الاختبار: مجاني، وبلا حد زمني، ودون موافقة تنتظرونها. يُنشأ مفتاح الاختبار من البوابة، ويمرّ أول أداء ببطاقة الاختبار — وإن فضّلتم، حدّثونا أولًا عن إدماجكم.