توثيق واجهة البرمجة

توثيق الواجهة البرمجية

استخلصوا بالبطاقة أو نقدًا، وأديروا الزبناء والاشتراكات والاسترجاعات من نظامكم. كل وحدة مشروحة، وكل نقطة نهاية مفصّلة، وكل شيء قابل للتجربة في السندبوكس.

وحدات: 12وحدات
نقاط نهاية: 62نقاط نهاية
كائنات موثّقة: 48كائنات موثّقة
إصدار الواجهة: v1.0.0إصدار الواجهة

مرجع مُولَّد من مواصفة OpenAPI التي تنشرها الواجهة نفسها — فلا يمكنه أن يحيد عن العقد.

البيئات

عنوان أساسي واحد — هو نفسه في الاختبار والإنتاج. مفتاحكم هو الذي يختار البيئة: مفتاح الاختبار لا يمكنه أن يمسّ الإنتاج، والعكس صحيح أيضًا. فأنتم لا تبدّلون العنوان أبدًا بين تجاربكم وإطلاقكم الفعلي — بل تبدّلون المفتاح.

https://api-psp.charipay.ma

السندبوكسchari_sk_test_…

لا حركة أموال حقيقية. بطاقة الاختبار مقبولة، وتُرسَل الويب هوكس كالمعتاد، ونقطة فرض استحقاق الاشتراك موجودة هنا فقط.

الإنتاجchari_sk_live_…

أموال حقيقية. يجب تفعيل الوصول على حسابكم: وإلى أن يُفعَّل، تردّ الواجهة 403 برمز PRODUCTION_ACCESS_NOT_ENABLED.

بطاقة اختبار السندبوكس

تعمل السندبوكس على مسارات حقيقية مقابل بيئة اختبار: المسارات حقيقية، أما المال فلا. وبطاقة واحدة فقط مقبولة فيها.

هذا الـ PAN هو الوحيد المقبول. أي رقم آخر — بما فيه 4242… الخاص بمنصات أخرى — يُرفض عند المنبع — عادةً بخطأ 502 — مع الرمز الثابت BAAS_CHARI_ERROR. إن واجهتم هذا الخطأ أثناء الاختبار، فتحققوا أولًا من البطاقة المُدخلة.

ما الذي تتيحه لكم الواجهة

بكلمات بسيطة

كل ما تفعلونه في بوابة ChariPay — استخلاص واسترجاع وتتبّع للمال — يستطيع برنامجكم فعله وحده عبر الواجهة البرمجية. تخبركم هذه الصفحة من أين تبدؤون حسب منتجكم.

لستم بحاجة إلى إدماج كل شيء: اختاروا المدخل الذي يناسب طريقة بيعكم — وبقية الواجهة تُضاف حين يطلبها منتجكم.

رابط الدفع

لمن

تبيعون بلا موقع إلكتروني — عبر واتساب أو الهاتف أو عرض ثمن أو مباشرة في المحل.

تقنيًا

‏POST /v1/payment-links يعيد رابط دفع مستضافًا للمشاركة، مع رمز QR وملصق PDF جاهز للطباعة. نداء واحد يكفي.

جلسة الأداء

لمن

لديكم موقع تجارة إلكترونية وتريدون الأداء داخل مسار الطلبية.

تقنيًا

تصبح الطلبية جلسة: توجّهون المشتري إلى صفحة الدفع المستضافة وتؤكدون عبر الويب هوك. لا بيانات بطاقة عندكم.

الدفع المباشر

لمن

تريدون تصميم شاشة الأداء الخاصة بكم، حقلًا حقلًا.

تقنيًا

‏Verify → submit → ‎3-D Secure → return: تقودون كل خطوة. بالمقابل، يدخل امتثال البطاقات في نطاقكم.

البداية — من الصفر إلى أول نداء

بكلمات بسيطة

أنشئوا حساب اختبار مجانيًا ونفّذوا نداءكم الأول في دقائق — بلا موعد، بلا التزام، بلا بطاقة بنكية.

لا تحتاجون إلى شيء للبدء: لا حساب قائم، ولا بريد إلى الدعم، ولا موعد تجاري. ثماني خطوات تفصل صفحة بيضاء عن نداء مُصادَق عليه في السندبوكس.

1. سجّلوا. POST /api/public/sandbox-signup عمومي. تصرّحون فيه ببريدكم المهني؛ ونرسل إليكم رابط تفعيل.

2. فعّلوا حسابكم. يحمل الرابط رمز تفعيل، تمرّرونه إلى POST /api/public/sandbox-signup/set-password مع كلمة السر التي تختارونها. ولا يُعاد هذا الرمز أبدًا في أي استجابة للواجهة: لا يوجد إلا في البريد.

3. سجّلوا الدخول إلى البوابة. يتحقق POST /api/v1/auth/login من بيانات دخولكم. وبحسب صلاحيات حسابكم، قد تطلب البوابة أولًا تسجيل تطبيق TOTP (رمز QR، ثم رمز من ست خانات عند كل دخول) — احتفظوا برموز الاسترداد.

4. اختاروا شركتكم. يؤكد POST /api/v1/auth/select-company الشركة التي تعملون عليها: هذه الاستجابة — لا الدخول — هي التي تحمل رمز الجلسة (JWT).

5. اجتازوا المصادقة المعزَّزة (step-up). إنشاء مفتاح API فعل حساس: يُصدر POST /api/v1/auth/step-up رمز تأكيد قصير العمر، مطلوبًا في الخطوة السابعة.

6. اطّلعوا على الصلاحيات المتاحة. يسرد GET /api/v1/api-keys/available-permissions النطاقات التي يمكن لحسابكم منحها لمفتاح. لا تمنحوا إلا ما يستدعيه إدماجكم فعلًا.

7. أنشئوا مفتاحكم. يولّده POST /api/v1/api-keys بالصلاحيات المختارة. ويُعرض المفتاح الكامل مرة واحدة فقط، في تلك اللحظة — ضعوه فورًا في خزنة أسرار أو متغير بيئة.

8. تحققوا من أن كل شيء يستقيم. GET /v1/wallet بمفتاحكم الجديد: إن أجابكم الرصيد، فإدماجكم مُصادَق عليه ويمكنكم البدء.

لاحظوا أن الخطوات من 1 إلى 3 لا تتطلب مصادقة، وأن الخطوات من 4 إلى 7 تنتمي إلى جلسة البوابة، وأن الخطوة 8 هي أولى الخطوات التي تستعمل مفتاح API. وهذا هو الموضع الوحيد في الواجهة الذي تلتقي فيه الأنظمة الثلاثة.

تفصيل يوفّر ساعة من الحيرة: لنقاط التسجيل والبوابة (الخطوات 1 إلى 7) صيغة أخطاء خاصة بها برموز ERR-XXXX. أما الغلاف الموصوف في دليل الأخطاء فيسري على واجهة التاجر — تلك التي يناديها مفتاحكم.

المصادقة

بكلمات بسيطة

مفتاح سري يعرّف برنامجكم عند كل نداء، كشارة دخول. مفتاح الاختبار ومفتاح الإنتاج شارتان مختلفتان: مفتاح الاختبار لا يلمس المال الحقيقي أبدًا.

كل طلب يحمل مفتاح الواجهة في ترويسة. لا رمز يُجدَّد ولا مسار OAuth: المفتاح يكفي، وهو الذي يحدّد البيئة.

يبدأ مفتاح السندبوكس بـ chari_sk_test_، ومفتاح الإنتاج بـ chari_sk_live_. فأنتم لا تختارون البيئة في العنوان ولا في ترويسة: تختارونها باختيار المفتاح. وهذا مقصود — إذ يجعل إرسال طلب اختباري إلى الإنتاج بالخطأ أمرًا مستحيلًا.

المفتاح سرّ. يعيش على خادمكم، في متغيّر بيئة أو خزنة أسرار. ولا ينبغي أن يظهر أبدًا في شيفرة تُرسَل إلى المتصفح، ولا في تطبيق جوال، ولا في مستودع git، ولا في لقطة شاشة.

نقاط /checkout/* هي الاستثناء: تحملها جلسة الدفع نفسها، ويحميها مفتاح تحقق أحادي الاستعمال. لا ترسلوا مفتاح الواجهة إليها أبدًا — فهي وحدها ما ينفّذه متصفّح المشتري.

Idempotency — إعادة النداء دون ازدواج

بكلمات بسيطة

إذا انقطعت الشبكة وأعاد نظامكم إرسال الطلب نفسه مرتين، فلن يُخصم من زبونكم مرتين أبدًا. هذه هي الآلية التي تضمن ذلك — وكيف تحسنون استعمالها.

انقطاع الشبكة بين خادمكم وخادمنا يترككم في شك: هل مرّ الإنشاء؟ وفي الأداء، إعادة المحاولة على غير هدى أسرع طريق إلى استخلاص المبلغ مرتين من الزبون نفسه.

آليتان مستقلتان تجيبان عن عطبين مختلفين. تتراكمان معًا، والصواب هو معرفة أيّهما يحميكم من ماذا.

ترويسة Idempotency-Key تحمي من إعادة المحاولة الشبكية. ترسلونها مع عمليات الإنشاء؛ وإعادة نداء بالقيمة نفسها تعيد النتيجة الأولى بدل إنشاء نسخة مكررة. إنها الحماية من انتهاء المهلة، أو انقطاع الاتصال، أو عميل HTTP يعيد المحاولة من تلقاء نفسه.

حقل externalId يحمي من إعادة الإصدار من جانبكم. إنه فريد لكل حساب ولكل بيئة: فإنشاء مورد بـ externalId موجود سلفًا يعيد المورد القائم بحالة 200 OK، بينما يجيب الإنشاء الحقيقي بـ 201 Created. إنها الحماية من نظامكم نفسه حين يعيد إصدار النية ذاتها — مهمة أُعيد تشغيلها، أو طابور أُعيد تمريره، أو نقرة مزدوجة في المكتب الخلفي.

لذا اختبروا الحالة، لا الجسم وحده: 201 تعني «أنشأتُه للتو»، و200 تعني «كان موجودًا سلفًا». وكلاهما نجاح.

والاسترجاعات تستعمل refundReference للسبب نفسه. اشتقّوها من معرّف الطلب — لا من العشوائية أبدًا: المرجع الحتمي يجعل إعادة النداء آمنة، والمرجع العشوائي يسترجع مرتين. وانتبهوا إلى الحالات: الاسترجاع الجديد يجيب بـ202 Accepted — يُنفَّذ لاتزامنيًا — وإعادة النداء بـ200. لا 201 أبدًا.

قد يوجد externalId نفسه مرة في السندبوكس ومرة في الإنتاج دون تعارض: فإزالة تكراره محصورة في البيئة. أما حاجز Idempotency-Key عند الإنشاء فمحصور في الحساب — فاحتفظوا بمفاتيح idempotency متمايزة بين اختباراتكم وإنتاجكم.

الأخطاء

بكلمات بسيطة

حين يفشل نداء، تجيب الواجهة دائمًا بالشكل نفسه: رمز ثابت لبرنامجكم، ورسالة مقروءة للإنسان، ومعرّف تعطونه للدعم.

تتقاسم كل أخطاء واجهة التاجر (/v1) الغلاف نفسه: code ثابت يستطيع برنامجكم اختباره، وmessage مقروء، وcorrelationId تقدمونه للدعم.

اختبروا الـ code لا الـ message أبدًا. فقد يُعاد صوغ الرسالة أو تُترجم أو تُوضَّح؛ أما الرمز فجزء من العقد.

ويُعاد الـ correlationId في كل الاستجابات، بما فيها الناجحة. سجّلوه بشكل منهجي: فهو ما يتيح العثور على طلب بعينه في سجلاتنا.

الرموز الأكثر تكرارًا: VALIDATION_ERROR (400، حقل لا يمرّ)، وUNAUTHORIZED (401، مفتاح غائب أو غير صالح)، وFORBIDDEN (403، صلاحية ناقصة في المفتاح)، وPRODUCTION_ACCESS_NOT_ENABLED (403، مفتاح إنتاج على حساب غير مفعَّل بعد)، وWALLET_NOT_ACTIVE (422، الطلب صحيح لكن قاعدة عملية تمنعه)، وRATE_LIMITED (429، خفّفوا الوتيرة واقرؤوا Retry-After).

أما أخطاء 5xx فمن جانبنا: أعيدوا النداء بمفتاح Idempotency بدل إنشاء مورد جديد.

ثلاث قواعد تسري على الواجهة كلها: أرسلوا X-Request-Id الخاص بكم — يُعاد على الاستجابة ويصير correlationId؛ وعلى النقاط المكشوفة للعموم، اقرؤوا X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset لضبط وتيرتكم؛ وكل عنوان تصرّحون به (عودة أو إشعار) يجب أن يكون بـhttps:// وإلا فخطأ 400. وأخيرًا تسامحوا مع قيم enum الجديدة والحقول الاختيارية الغائبة — لا null أبدًا: هكذا تتطور الواجهة دون أن تكسركم.

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "amount: must be greater than 0"
  },
  "correlationId": "b0c1e2d3-4f56-7890-abcd-ef0123456789"
}

الحالة	الرموز	المعنى
400	INVALID_IDEMPOTENCY_KEY · MISSING_PARAMETER · VALIDATION_ERROR	طلب غير صحيح البنية أو فشل في التحقق (code = VALIDATION_ERROR / MISSING_PARAMETER).
401	INVALID_TOKEN · UNAUTHORIZED	مفتاح API مفقود أو غير صالح (code = UNAUTHORIZED).
403	FORBIDDEN · PRODUCTION_ACCESS_DENIED	تمت المصادقة لكن المفتاح يفتقر إلى الصلاحية المطلوبة، أو أن الوصول إلى الإنتاج غير مفعّل (code = FORBIDDEN / PRODUCTION_ACCESS_DENIED).
404	OPERATION_NOT_FOUND · ORDER_NOT_FOUND · SESSION_NOT_FOUND	لا يوجد رابط كهذا لهذا الحساب.
409	IDEMPOTENCY_CONFLICT · SESSION_ALREADY_CONSUMED · SESSION_NOT_ACTIVE	الجلسة مدفوعة أو ملغاة مسبقًا (SESSION_ALREADY_CONSUMED / SESSION_NOT_ACTIVE).
410	SESSION_EXPIRED	انتهت صلاحية الجلسة (SESSION_EXPIRED).
422	PAYMENT_METHOD_CONSENT_REQUIRED · WALLET_NOT_ACTIVE	صالح من حيث الصياغة، لكن قاعدة عمل تمنعه (مثلًا WALLET_NOT_ACTIVE).
429	RATE_LIMITED	تم تجاوز حد المعدّل (code = RATE_LIMITED). أعيدوا المحاولة بعد المهلة المحدّدة في ترويسة Retry-After.

القوائم والتصفّح

بكلمات بسيطة

القوائم الطويلة — المعاملات، الزبناء — تصل صفحة صفحة. هكذا تتصفحونها دون أن يفوتكم شيء.

نقاط القوائم مقسّمة إلى صفحات وتعيد دائمًا الغلاف نفسه: محتوى الصفحة، ورقمها، وحجمها، وإجمالي العناصر، وإجمالي الصفحات.

يبدأ الترقيم من الصفر. لا تفترضوا أبدًا أن قائمة تسع في صفحة واحدة — تصفّحوها حتى totalPages.

وفي المعاملات، فضّلوا الترقيم بالمؤشر للمسح الطويل: اطلبوا limit ثم مرّروا cursor = nextCursor ما دام hasMore صحيحًا. فهو لا يتخطى سطرًا ولا يكرره حين تصل معاملات جديدة أثناء المسح.

وللتصدير الكبير، تبثّ نقطة المعاملات المخصّصة ملف CSV بدل سلسلة صفحات (حتى 10 000 سطر — وبعدها قسّموا بالفترة عبر from/to): أسرع وأأمن للمطابقة المحاسبية.

ويب هوكس

بكلمات بسيطة

بدل سؤال الواجهة مرارًا هل تمّ الأداء، دعوها تخبركم: لحظة تحرك المال، ينادي ChariPay خادمكم برسالة موقَّعة. هذه أهم قطعة في إدماج موثوق.

لا يكتمل الأداء لحظة ندائكم إياه: يمرّ المشتري عبر بنكه، ويجتاز ‎3-D Secure، ثم يعود. لذلك تصلكم النتيجة عبر ويب هوك، وهو المرجع — لا إعادة توجيه المتصفح التي قد يقطعها المشتري بإغلاق نافذته. والاستطلاع الدوري بديل احتياطي، لا مصدرًا للحقيقة.

تصرّحون بعناوين الاستقبال من الواجهة، مع لائحة صريحة بالأحداث. لا تشتركوا إلا فيما تعالجونه: فكل حدث زائد فرصة لخلل وحِمل على خادمكم.

يجب أن يكون العنوان HTTPS عموميًا، على المنفذ 443. ويُرفض localhost والعناوين الخاصة عند التسجيل — وفي التطوير، استعملوا نفقًا.

التوقيع. تحمل كل عملية تسليم X-CHARI-SIGNATURE: وهو HMAC-SHA256 بالنظام الست عشري بحروف صغيرة، محسوب على السلسلة الطابع الزمني + "." + الجسم الخام. والطابع الزمني في X-CHARI-TIMESTAMP، بـالميلي ثانية منذ epoch.

أربع قواعد تحمل أمن التحقق كله: احسبوا الـ HMAC على البايتات الخام قبل أي تحليل — فـ JSON مُعاد تسلسله لا ينتج التوقيع نفسه؛ وارفضوا طابعًا زمنيًا يزيد انحرافه عن ±5 دقائق، كما نفعل نحن؛ وقارنوا في زمن ثابت (timingSafeEqual)، لا بـ === أبدًا؛ وأثناء تدوير السر، اقبلوا أحد التوقيعين.

أثناء التدوير، وما دام السر القديم في مهلة السماح، نرسل الجسم نفسه موقَّعًا مرتين: X-CHARI-SIGNATURE بالسر القديم وX-CHARI-SIGNATURE-NEXT بالجديد. تحققوا بالسر الذي بحوزتكم، ثم انتقلوا.

أزيلوا التكرار اعتمادًا على Chari-Event-Id، لا على Chari-Webhook-Id. وهذا الفرق أغلى ما يُخطأ فيه: فالحدث المنطقي الواحد قد يُسلَّم عدة مرات، وتنال كل محاولة Chari-Webhook-Id خاصًا بها — يتغير إذن في كل محاولة — لكنها جميعًا تحمل Chari-Event-Id نفسه. وإزالة التكرار بالمعرّف الخطأ تعني معالجة الأداء نفسه مرتين.

والتسليم مرة واحدة على الأقل، وقد يصل خارج الترتيب: سترون تكرارات، وهذا بالتصميم. ولا تجيبوا بـ 2xx إلا بعد أن يثبت التحديث العملي وقيد إزالة التكرار معًا — فكل جواب غير 2xx يُعاد. وأنجزوا العمل الثقيل في الخلفية: فمعالجة تستغرق عشر ثوانٍ تُطلق في النهاية إعادات تسليم، ثم تعليق عنوانكم. تنطلق المحاولة الأولى فورًا، ثم دقيقة → 5 دقائق → 30 دقيقة → ساعة → كل 6 ساعات، حتى 16 محاولة على مدى نحو 72 ساعة؛ وبعدها يُعلَّم التسليم فاشلًا. وبعد انقطاع أطول، طابقوا عبر GET /v1/transactions بدل انتظار ويب هوك لن يعود.

ويعود حقلا metadata وexternalId في أحداث المورد الذي حملهما: وهكذا تطابقون دون تخزين مراجعنا.

javascript

const crypto = require('crypto');

function verify(rawBody, signature, timestamp, secret) {
  // Fenêtre anti-rejeu de ±5 minutes — l'horodatage est en millisecondes.
  if (Math.abs(Date.now() - Number(timestamp)) > 5 * 60 * 1000) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  // Une signature malformée doit répondre false — jamais jeter (500 → retentatives).
  if (!/^[0-9a-f]{64}$/i.test(signature)) return false;

  // Comparaison en temps constant : jamais `===`.
  return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(signature, 'hex'));
}

الانتقال إلى الإنتاج

بكلمات بسيطة

يوم الإطلاق لا تغيّرون إلا شيئًا واحدًا: المفتاح. هذه القائمة تتأكد أن كل ما عداه جاهز قبل التبديل.

تُفتح السندبوكس فورًا؛ أما الإنتاج فيُفعَّل على حسابكم بعد التحقق من شركتكم. وإلى ذلك الحين يتلقّى مفتاح الإنتاج رمز 403 صريحًا.

قبل التبديل، بضع تحققات تستحق وقتها: معالجُ ويب هوك لديكم يتحمّل التكرار ويتحقق من التوقيع؛ وعملياتُ الإنشاء ترسل ترويسة Idempotency-Key؛ وتسجّلون correlationId لكل استدعاء؛ ومفاتيحكم في خزنة لا في مستودعكم؛ وقد اختبرتم استردادًا واحدًا على الأقل ودفعة فاشلة، لا المسار السعيد وحده.

يوم التبديل تغيّرون شيئًا واحدًا فقط: المفتاح. أما العناوين والحمولات ورموز الأخطاء فهي نفسها.

وحدات الواجهة البرمجية

اثنتا عشرة وحدة، مرتبة كما يجري إدماج حقيقي: ابدأوا بروابط الدفع أو صفحة الدفع، أضيفوا الويب هوكس، ثم الباقي حسب وتيرة منتجكم. لكل وحدة صفحتها، بنقاط النهاية الخاصة بها وحقولها وأمثلتها بأربع لغات.

7 نقاط نهاية

روابط الدفع

مبلغ ووصف ورابط تُرسلونه. يدفع الزبون على صفحة تستضيفها ChariPay — ولا تستضيفون أنتم أي بيانات بطاقة.

فتح الوحدة

4 نقاط نهاية

جلسات الدفع

يتحوّل طلب المتجر الإلكتروني إلى جلسة: توجّهون المشتري إلى صفحة الدفع المستضافة وتستعيدون النتيجة.

فتح الوحدة

4 نقاط نهاية

الدفع المباشر

الاستدعاءات التي تنفّذها صفحة الدفع نفسها: التحقق من الجلسة، وإرسال بيانات البطاقة، وعودة ‎3-D Secure.

فتح الوحدة

4 نقاط نهاية

المعاملات

كل ما دخل وخرج: مدفوعات واستردادات ودفعات نحو البنك ورسوم. مع تفاصيل العملية وخطها الزمني.

فتح الوحدة

3 نقاط نهاية

الاستردادات

استرداد كامل أو جزئي لأداء ناجح، بسبب ومرجع من عندكم — يُخصم من رصيد المحفظة ويُقيَّد حركةً مستقلة مرتبطة بالمعاملة الأصلية.

فتح الوحدة

4 نقاط نهاية

المحفظة

رصيد حساب الأداء الخاص بكم، وRIB باسم التاجر، والشهادة القابلة للتنزيل، وتغذية الحساب.

فتح الوحدة

8 نقاط نهاية

الزبناء

سجل زبنائكم النهائيين ووسائل الأداء المحفوظة لديهم، لإعادة استعمالها في الاشتراكات والأداءات المتكررة دون إعادة إدخال البيانات.

فتح الوحدة

6 نقاط نهاية

المنتجات

كتالوج بسيط بمنتجاتكم وطلباته، للبيع عبر روابط الدفع أو صفحة الدفع دون بناء متجر إلكتروني كامل.

فتح الوحدة

9 نقاط نهاية

الاشتراكات

خصم متكرر على وسيلة دفع محفوظة، باستحقاقاته وتوقّفاته ومحاولات اقتطاعه.

فتح الوحدة

10 نقاط نهاية

الويب هوكس

عناوين الاستقبال لديكم، وأسرار توقيعها، وقائمة الأحداث المُرسَلة، وتفاصيل كل تسليم.

فتح الوحدة

نقطة نهاية واحدة

كتالوج الأحداث

قائمة كل أنواع الأحداث التي يمكنكم الاشتراك فيها.

فتح الوحدة

2 نقاط نهاية

رحلة الزبون

ما جرى بين فتح رابط أو جلسة وبين الدفع: الخطوات المقطوعة، ونقاط التخلّي، ومصدر الزيارة.

فتح الوحدة

موارد للتنزيل

ما يلزمكم للعمل خارج المتصفح: المجموعة القابلة للتنفيذ، والعقد الذي تولّدون منه، والحزمة التي تسلّمونها لمساعد برمجي.

المسرد

الكلمات التي يستعملها هذا التوثيق بمعنى دقيق.

مفتاح الواجهة: السر الذي يصادق استدعاءاتكم ويختار البيئة. بادئة chari_sk_test_ في السندبوكس، وchari_sk_live_ في الإنتاج.
externalId: معرّفكم الخاص، تربطونه بمورد لتجدوه من نظامكم. فريد لكل حساب ولكل بيئة.
Idempotency-Key: ترويسة اختيارية على عمليات الإنشاء. استدعاءان بالمفتاح نفسه ينتجان موردًا واحدًا.
correlationId: معرّف يُعاد في كل استجابة. وهو ما سيطلبه الدعم للعثور على استدعاء.
رابط الدفع: صفحة دفع تستضيفها ChariPay، تُنشأ باستدعاء واحد، وتُشارَك كرابط أو رمز QR أو ملصق.
جلسة الدفع: طلب متجر إلكتروني يتحوّل إلى مسار دفع، بعناوين عودة تخصّكم.
‎3-D Secure: المصادقة القوية التي يطلبها بنك المشتري. تقطع المسار، وهي سبب وجود الويب هوكس.
ويب هوك: إشعار موقَّع نرسله إلى خادمكم عند وقوع حدث. وهو مصدر الحقيقة لأي دفعة.
المحفظة: حساب الأداء الخاص بالتاجر — تديره Chari Money، مؤسسة أداء مرخَّصة من بنك المغرب — برصيده وRIB باسم التاجر.
MAD: الدرهم المغربي. كل المبالغ في الواجهة بالوحدات الرئيسية — 249.00 تعني 249 درهمًا.

تحدّثوا إلى مختص دمج

سؤال حول الدمج؟

يجيب فريقنا التقني فرق الإدماج، من أول استدعاء في السندبوكس حتى الانتقال إلى الإنتاج.

اتصلوا بنا

توثيق الواجهة البرمجية

البيئات

بطاقة اختبار السندبوكس

ما الذي تتيحه لكم الواجهة

رابط الدفع

جلسة الأداء

الدفع المباشر

البداية — من الصفر إلى أول نداء

المصادقة

Idempotency — إعادة النداء دون ازدواج

الأخطاء

ويب هوكس

الانتقال إلى الإنتاج

وحدات الواجهة البرمجية

روابط الدفع

جلسات الدفع

الدفع المباشر

المعاملات

الاستردادات

المحفظة

الزبناء

المنتجات

الاشتراكات

الويب هوكس

كتالوج الأحداث

رحلة الزبون

موارد للتنزيل

مجموعة Postman

مواصفة OpenAPI

حزمة LLM بصيغة ZIP

المسرد

سؤال حول الدمج؟