اختبار الدفع الإلكتروني قبل الإطلاق: بطاقة الاختبار والسيناريوهات وحدود السندبوكس

لاختبار الدفع الإلكتروني دون مال حقيقي، أنشئوا مفتاحًا من نوع chari_sk_test_…، ونادوا API نفسها التي ستستعملونها في الإنتاج، وادفعوا ببطاقة الاختبار ‎4918 9141 0719 5005، مع CVV 123، وأي تاريخ انتهاء مستقبلي، ورمز ‎3-D Secure 555. المسار كامل — صفحة دفع مستضافة، ومصادقة، وويب هوك موقَّع، واسترداد، وتصدير — لكن لا يتحرك أي درهم. يقدّم هذا الدليل البطاقة والرمز، وما يغطيه السندبوكس وحدةً وحدة، وخطة اختبار من ستة سيناريوهات تُجرى قبل أي إطلاق، وما لا يمكن اختباره مع طريقة التحقق منه بشكل آخر.

وضع الاختبار: API نفسها ومفتاح اختبار

ChariPay منصة دفع مغربية، مزوّد خدمات دفع (PSP) تشغّله Chari Money، مؤسسة أداء مرخَّصة من بنك المغرب. ووضع الاختبار فيها ليس نموذجًا شكليًا: إنه API نفسها، على القاعدة نفسها https://api-psp.charipay.ma، بالمسارات نفسها والحمولات نفسها ورموز الأخطاء نفسها كما في الإنتاج. ما يتغير هو المفتاح. فالمفتاح الذي يبدأ بـchari_sk_test_ يعمل في السندبوكس، ومفتاح chari_sk_live_ يعمل في الإنتاج: لا تختارون البيئة في العنوان ولا في ترويسة، بل تختارونها حين تختارون المفتاح. والبيئتان معزولتان: يمكن أن يوجد externalId نفسه مرة في كل منهما.

يُفتح وضع الاختبار بمجرد تفعيل حسابكم، دون موافقة تنتظرونها: ابدؤوا في وضع الاختبار. ثلاثة حقول — الاسم، والبريد الإلكتروني المهني، والمؤسسة —، ثم رابط تفعيل يصلكم بالبريد لاختيار كلمة المرور، ثم بوابة التاجر حيث تنشئون بأنفسكم مفتاح الاختبار بعد إعادة مصادقة. ولا يُعرض المفتاح كاملًا إلا مرة واحدة ولا يُرسل أبدًا بالبريد الإلكتروني: احفظوه فورًا في متغير بيئة أو في خزنة أسرار، ولا تضعوه أبدًا في المستودع. ويجري التحقق من مؤسستكم (KYB) بالتوازي ولا يشترطه إلا الانتقال إلى الإنتاج.

وضع الاختبار مجاني، بلا حد زمني وبلا التزام؛ وتفصّل صفحة الأسعار ما لا يسري إلا عند الانتقال إلى الإنتاج. أما الأعراف المشتركة بين كل النداءات — المصادقة، والترقيم، والـIdempotency، والأخطاء — فمرجعها فضاء المطورين وتوثيق API.

بطاقة الاختبار ورمز ‎3-D Secure

هذه هي البطاقة التي تُدخلونها في صفحة الدفع، كما يفعل الزبون؛ وهي تُطلق المسار الحقيقي — صفحة الدفع، ومصادقة ‎3-D Secure، والويب هوك.

هذه البطاقة هي الوحيدة المقبولة، ولا يتحرك أي مال حقيقي. وأي بطاقة أخرى — بطاقتكم، أو بطاقة زميل، أو رقم اختبار منقول من منصة أخرى — تُرفض بالرد 502 والرمز BAAS_CHARI_ERROR. فإن ظهر لكم هذا الرد أثناء الاختبار، تحققوا من البطاقة المُدخلة قبل البحث عن خلل في شفرتكم؛ أما ردود الأخطاء الأخرى فمشروحة واحدًا واحدًا في رموز أخطاء API الدفع.

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

ما يغطيه سندبوكس الدفع، وحدةً وحدة

ستة مجالات تُختبر من البداية إلى النهاية بمفتاح اختبار. لكل منها، هذه طريقة إطلاقه وما ينبغي مراقبته.

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

اختبار الدفع الإلكتروني من البداية إلى النهاية، خطوة بخطوة

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

curl -X POST 'https://api-psp.charipay.ma/v1/payment-sessions' \
  -H 'X-CHARI-PAY-API-KEY: chari_sk_test_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-2026-0421-session' \
  -d '{
    "amount": 250.00,
    "orderId": "ORD-2026-0421",
    "externalId": "order-2026-0421",
    "config": {
      "customer": {
        "email": "amine.bennani@example.com",
        "firstName": "Amine",
        "lastName": "Bennani",
        "phone": "+212600000000"
      },
      "urls": {
        "accept": "https://votre-boutique.ma/paiement/succes",
        "decline": "https://votre-boutique.ma/paiement/echec",
        "notification": "https://votre-boutique.ma/webhooks/charipay"
      }
    },
    "metadata": { "cartId": "c_987", "source": "web" }
  }'

يحتوي الرد — 201، أو 200 إن أعدتم إرسال externalId نفسه — على هذه الحقول الخمسة، ولا شيء غيرها:

{
  "sessionId": "ps_5Kd0Rn",
  "sessionToken": "st_…",
  "verifyKey": "vk_5Kd0Rn",
  "expiresAt": "2026-10-05T10:15:00Z",
  "checkoutUrl": "https://…/checkout/ps_5Kd0Rn"
}

الحالة والمبلغ ليسا في هذا الرد: يُقرآن عبر GET /v1/payment-sessions/{sessionId}. ثم اجتازوا المسار كما سيعيشه زبونكم:

1. 1سجّلوا `sessionId` مقابل طلبيتكم، في حالة «في انتظار الأداء».
2. 2افتحوا `checkoutUrl` كما ورد في الرد، في متصفح، كما سيفعل المشتري.
3. 3ادفعوا ببطاقة الاختبار، ثم أدخلوا 555 في خطوة ‎3-D Secure.
4. 4عودوا إلى عنوان `accept`: تعرض صفحتكم حالة انتظار، لا تأكيدًا بعد.
5. 5استقبلوا الحدث الموقَّع payment.succeeded في نقطة الاستقبال الخاصة بالسندبوكس، وتحققوا من توقيعه، وأكّدوا الطلبية في تلك اللحظة.
6. 6أعيدوا قراءة الحالة عبر GET /v1/payment-sessions/{sessionId} للتأكد من أن قاعدة بياناتكم وقاعدتنا تقولان الشيء نفسه.

ترتيب الخطوتين 4 و5 غير مضمون، وهذا بالضبط ما ينبغي أن يُثبته الاختبار: أكّدوا الطلبية عند استلام الويب هوك، لا عند إعادة التوجيه وحدها: فإعادة التوجيه تعني أن المشتري عاد، لا أن الأداء قد تمّ. وتذكّروا أيضًا أن عنوان notification، مثل أي نقطة استقبال مسجَّلة، يجب أن يكون متاحًا عبر HTTPS عمومي: على جهاز تطوير، تحتاجون إلى نفق.

والبديل دون جلسة هو رابط الدفع.

curl -X POST 'https://api-psp.charipay.ma/v1/payment-links' \
  -H 'X-CHARI-PAY-API-KEY: chari_sk_test_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1042-link' \
  -d '{
    "amount": 149.90,
    "description": "Commande #1042",
    "singleUse": true,
    "externalId": "order-1042",
    "customerEmail": "amine.bennani@example.com",
    "customerPhone": "+212600000000",
    "metadata": { "cartId": "c_987" }
  }'

يعطيكم الرد reference الرابط (pl_…) وpayUrl الخاص به: افتحوا payUrl، وادفعوا ببطاقة الاختبار، ثم اقرؤوا حالة الرابط عبر GET /v1/payment-links/{reference}. ويعيد دليل API الدفع في المغرب هذين النداءين إلى سياق الإدماج الكامل.

خطة اختبار من ستة سيناريوهات

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

قواعد قليلة تجعل هذه الخطة موثوقة. يُختبر الاسترداد الجزئي على أداء غير الذي يُختبر عليه الاسترداد الكلي، ويحدّد كل استرداد أداءه بـoperationId الذي يُقرأ في GET /v1/transactions. وفي السيناريو 4، أعيدوا أيضًا Idempotency-Key نفسه بجسم معدَّل، يشمل externalId جديدًا: الرد المنتظر هو 409 IDEMPOTENCY_CONFLICT، وعلى شفرتكم أن تعامله كخطأ من جهتكم، لا كعطل في الشبكة. أما إن بقي externalId نفسه، فتعود الجلسة الموجودة بالرد 200. والآلية كاملة مشروحة في Idempotency في المدفوعات.

ولا تبنوا أي مسار تجاري يتوقف على payment.failed: فهذا الحدث لا يُرسل إلا إذا طلبتموه عند إنشاء الجلسة (notifyOnFailure). يُكتشف الفشل بقراءة الحالة، والطلبية التي لم تُؤكَّد تبقى في الانتظار إلى أن تنتهي صلاحية جلستها. وأخيرًا، يُجرى السيناريو 6 بالتفصيل في اختبار الويب هوك محليًا: نفق HTTPS، وحدث الاختبار، وسجل التسليمات.

الاشتراكات والويب هوك والتصدير: التحققات المنسية

الاشتراكات. اشتراك ChariPay سلسلة من روابط الدفع، رابط لكل استحقاق يُرسل إلى الزبون بالبريد الإلكتروني: ويُختبر بتقصير الجدول الزمني. أنشئوا الزبون (POST /v1/clients) ثم الاشتراك (POST /v1/subscriptions) بـstartDate بتاريخ اليوم وبالدورية DAILY: يُنشأ الرابط الأول فورًا ويُعاد في currentCharge، ويبقى الاشتراك INCOMPLETE إلى حين أدائه. أدّوا هذا الرابط ببطاقة الاختبار، في صفحة الدفع المستضافة مع ‎3-D Secure: ينتقل الاشتراك إلى ACTIVE ويصلكم subscription.payment_succeeded. وفي اليوم الموالي، يُفتح استحقاق ثانٍ برابط جديد يُؤدّى بالطريقة نفسها. والحقول والأحداث وخطة الاختبار الكاملة مفصّلة في دمج الاشتراكات عبر API.

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

التصدير. صدّروا معاملات اختباركم — من بوابة التاجر أو عبر GET /v1/transactions/export.csv — وتحققوا من أمرين. تحمل كل حركة مرجع البيع أو الاسترداد أو الدفعة التي تفسّرها، ويظهر الاسترداد كحركة مستقلة مرتبطة بالمعاملة الأصلية. والطوابع الزمنية بتوقيت UTC؛ والمغرب على UTC+1: فعلى أداة المطابقة لديكم أن تحوّل، وإلا سقط أداء تمّ بعد منتصف الليل بقليل على اليوم السابق.

ما لا يُختبر، وكيف تتحققون منه بطريقة أخرى

السندبوكس لا يَعِد بكل شيء. ثلاثة أمور تبقى خارج نطاقه:

• إيداع نقدي حقيقي في الوكالة. أنشئوا الرابط لاستعمال واحد مع paymentMethod: "CASH" وتحققوا من أن شفرتكم تعرف كيف تقرأ حالته. في الإنتاج، بمجرد أن تؤكد الشبكة الإيداع، يصبح الرابط «مدفوعًا» ويصلكم الإشعار في بوابة التاجر؛ ومن جهة الخادم تُقرأ حالة الرابط عبر GET /v1/payment-links/{reference}. أما الإيداع نفسه فلا يجري في السندبوكس.
• تحويل بنكي حقيقي أو أداء فاتورة حقيقي. يجري مسار التحويل في بوابة التاجر — وفي السندبوكس يُقبل أي رمز من ستة أرقام لتأكيد الإرسال —، لكن لا يتلقى أي مستفيد ولا أي دائن شيئًا.
• أي بطاقة غير بطاقة الاختبار. تتلقى 502 BAAS_CHARI_ERROR. وسلوك البطاقة الحقيقية — المصادقة لدى البنك المُصدِر، وانفتاحها على الأداء عبر الإنترنت — لا يُرى إلا في الإنتاج.

يُتحقَّق من هذه المسارات الثلاثة على عمليات حقيقية، بعد تفعيل حسابكم: في بوابة التاجر وفي التصدير. أما السندبوكس فلا يختفي بعد الإطلاق: يبقى بيئة الاختبار لديكم. احتفظوا بمجموعتين من متغيرات البيئة واختبروا كل تطوير في السندبوكس قبل نشره. وعند الانتقال إلى الإنتاج، لا تغيّرون سوى المفتاح وسرّ الويب هوك: فالعناوين والحمولات ورموز الأخطاء متطابقة. وإلى أن يُفعَّل الإنتاج، يتلقى مفتاح chari_sk_live_… الرد 403 PRODUCTION_ACCESS_NOT_ENABLED. أما قائمة يوم الانتقال فتجدونها في الانتقال من السندبوكس إلى الإنتاج.

أسئلة شائعة

أي بطاقة اختبار أستعمل لاختبار الدفع الإلكتروني؟

البطاقة ‎4918 9141 0719 5005، مع CVV 123، وأي تاريخ انتهاء مستقبلي، ورمز ‎3-D Secure 555. إنها البطاقة الوحيدة المقبولة في السندبوكس: تُطلق المسار كاملًا — صفحة الدفع، والمصادقة، والويب هوك الموقَّع — دون أن يتحرك أي مال حقيقي. وأي بطاقة أخرى تُرفض بالرد 502 والرمز BAAS_CHARI_ERROR.

أي رمز ‎3-D Secure أُدخل في وضع الاختبار؟

أدخلوا 555 في خطوة المصادقة، بعد إدخال بطاقة الاختبار. هذه الخطوة تحاكي التي يجتازها زبناؤكم في الإنتاج مع بنكهم: فهي تتحقق من أن مساركم يتحمّل إعادة التوجيه نحو المصادقة ثم العودة إلى عنوان accept لديكم. ولا يوجد رمز آخر موثَّق للسندبوكس.

هل يمكن اختبار أداء ببطاقتي الحقيقية في السندبوكس؟

لا. في السندبوكس تُقبل بطاقة الاختبار وحدها: فالبطاقة الحقيقية، أيًّا كان البنك الذي أصدرها، تُرفض بالرد 502 والرمز BAAS_CHARI_ERROR. أما سلوك البطاقة الحقيقية — المصادقة لدى البنك المُصدِر، وانفتاحها على الأداء عبر الإنترنت — فلا يُلاحَظ إلا في الإنتاج، بعد أن يُفعَّل حسابكم.

هل يجب انتظار التحقق من مؤسستي لاستعمال وضع الاختبار؟

لا. يُفتح وضع الاختبار بمجرد تفعيل حسابكم، دون موافقة تنتظرونها: تنشئون مفتاح الاختبار من بوابة التاجر وتدفعون ببطاقة الاختبار. ويجري التحقق من مؤسستكم (KYB) — وثائق الهوية والسجل التجاري — بالتوازي ولا يشترطه إلا الانتقال إلى الإنتاج. وهكذا يستطيع فريقكم التقني بناء الإدماج واختباره بينما يُدرس ملفكم.

كيف أحاكي أداءً لم يكتمل في وضع الاختبار؟

لا تُنشر أي بطاقة «للرفض»: يُستحث الفشل عبر المسار. أغلقوا التبويب في خطوة ‎3-D Secure لمحاكاة التخلي، أو أنشئوا جلسة بـexpiresAt قريب واتركوها تنتهي. ثم تحققوا من أن الطلبية لم تُؤكَّد — تبقى في الانتظار بعد التخلي، وتنتقل إلى الحالة التي خطّطتم لها بعد انتهاء الصلاحية —، واقرؤوا الحالة عبر GET /v1/payment-sessions/{sessionId}. ولا تبنوا أي منطق على payment.failed، فهو لا يُرسل إلا إذا طلبتموه.

هل يمكن اختبار الأداء نقدًا في الوكالة داخل السندبوكس؟

ليس الإيداع نفسه: لا يجري أي إيداع نقدي حقيقي في السندبوكس. يمكنكم في المقابل إنشاء الرابط لاستعمال واحد مع paymentMethod: "CASH" والتحقق من أن شفرتكم تقرأ حالته عبر GET /v1/payment-links/{reference}. وفي الإنتاج، بمجرد أن تؤكد الشبكة الإيداع، يصبح الرابط «مدفوعًا» ويصلكم الإشعار في بوابة التاجر.

كيف أختبر عدة استحقاقات لاشتراك؟

أنشئوا الاشتراك بـstartDate بتاريخ اليوم وبالدورية DAILY، بمفتاح السندبوكس. يُنشأ رابط الدفع الأول فورًا ويُعاد في currentCharge: أدّوه ببطاقة الاختبار، رمز ‎3-D Secure 555، فتلاحظون subscription.payment_succeeded في نقطة الاستقبال لديكم. وفي اليوم الموالي، يُفتح استحقاق ثانٍ برابط جديد: في ثلاثة أيام، ترون ثلاثة استحقاقات. وخطة الاختبار الكاملة مفصّلة في دليل دمج الاشتراكات عبر API.

هل يُرسل الويب هوك في وضع الاختبار؟

نعم، كالمعتاد: الأداءات والاستردادات والاستحقاقات التي تُجرى في وضع الاختبار تُطلق أحداثها الموقَّعة نحو نقطة الاستقبال المسجَّلة بمفتاح الاختبار. وهذه النقطة تنتمي إلى السندبوكس ولها سرّها الخاص، المختلف عن سرّ الإنتاج. ولاختبار مستقبِلكم دون أداء، أرسلوا حدث الاختبار: payment.succeeded اصطناعي يحمل Test: true، ولا يقابله أي أداء حقيقي.

الخطوة التالية

أنشئوا حسابكم ومفتاح الاختبار — ابدؤوا في وضع الاختبار —، ثم أجروا السيناريوهات الستة لهذه الخطة على إدماجكم، بالترتيب، ببطاقة الاختبار. يأتي بعد ذلك ضبط مستقبِل الأحداث مع اختبار الويب هوك محليًا، وتأتي قائمة الانتقال في الأخير مع الانتقال من السندبوكس إلى الإنتاج.