باختصار
- الإيداع بالبطاقة يغذّي محفظة المستخدم من بطاقته البنكية. وهو إحدى طرق تغذية الرصيد، إلى جانب الإيداع النقدي لدى وكيل.
- المسار: معاينة الرسوم، ثم التنفيذ، ثم مصادقة 3-D Secure، ثم ويب هوك الإيداع بالبطاقة المأذون به، ثم التحقق من العملية.
- القاعدة الذهبية: يُحدَّث الرصيد عند التأكيد (الويب هوك وقراءة العملية)، لا عند إعادة التوجيه وحدها.
- لا يجب الخلط بينه وبين استخلاص تاجر لثمن مشترياته، الذي يعود إلى منصة دفع.
لماذا نقترح الإيداع بالبطاقة
المحفظة التي لا توجد طريقة بسيطة لتغذيتها تبقى فارغة. وفي المغرب، يتكامل مدخلان: النقد، الذي يودَع لدى وكيل من الشبكة بفضل مرجع، والبطاقة البنكية، من الهاتف وفي أي وقت. ويضع دليلنا حول المحفظة الإلكترونية في المغرب هذه الاستعمالات في سياقها، وتصف صفحة المحفظة عبر الهاتف في المغرب عرض Chari Money بالعلامة البيضاء.
ويتوجه الإيداع بالبطاقة إلى التطبيقات التي تمنح مستخدميها رصيدًا: تطبيق شامل، أو تطبيق توصيل يصرف مداخيل عمال التوصيل، أو منصة خدمات. فالأمر لا يتعلق باستخلاص ثمن مشتريات، بل بتحويل مال البطاقة إلى رصيد في المحفظة.
المتطلبات المسبقة
- مفتاح API نشط لبيئة sandbox، يُطلب من توثيق API.
- زبون مسجَّل: يُقيَّد الإيداع في المحفظة المرتبطة برقم هاتفه. ويصف دليل «محفظة الزبون» في التوثيق التسجيل والتأكيد بالرمز والتفعيل.
- لتلقي الإشعارات: نقطة نهاية HTTPS ومفتاح الويب هوك الذي تقدّمونه لـChari Money، والذي يعود في الترويسة
X-Api-Keyلكل إشعار.
وفي بيئة sandbox، تتيح بطاقة اختبار موثَّقة ورمز 3-D Secure الخاص بها تجربة المسار كاملًا دون أي مال حقيقي. انظروا أيضًا صفحة بيئة sandbox لواجهة API الشركاء.
المسار خطوة بخطوة
1. معاينة الإيداع
قبل أي اقتطاع، يتحقق استدعاء المعاينة من إمكانية الإيداع ويُرجع الرسوم. ويُمرَّر رقم هاتف الزبون كمعامل في الطلب، والمبلغ في الجسم. اعرضوا على المستخدم المبلغ والرسوم والمجموع قبل أن يؤكد.
2. تنفيذ الإيداع
يحمل استدعاء التنفيذ بيانات البطاقة: الرقم، ورمز CVV، وتاريخ الانتهاء بصيغة السنة والشهر في أربعة أرقام. ويتيح خيار الاحتفاظ بالبطاقة في شكل رمز للإيداعات اللاحقة. ويكون 3-D Secure مفعّلًا افتراضيًا، ويشير الرد إلى ما إذا كانت إعادة التوجيه ضرورية، مع عنوان صفحة المصادقة.
3. إتمام مصادقة 3-D Secure
إذا طُلبت إعادة التوجيه، افتحوا العنوان المقدَّم في متصفح. يصادق حامل البطاقة لدى بنكه، ثم يُعاد توجيهه إلى عنوان النجاح أو الفشل لديكم. ويحمل عنوان العودة رمز رد، يساوي صفرًا عند النجاح، ورمز سبب مقروءًا. تحققوا من الاثنين لتحديد الشاشة الموالية.
4. تلقي ويب هوك الإيداع بالبطاقة المأذون به
عندما يُقبل الإيداع بالبطاقة، تُشعر Chari Money نقطة النهاية لديكم بحدث الإيداع بالبطاقة المأذون به، بطلب POST بصيغة JSON. ويتضمن الجسم معرّف التتبع الخاص بكم، ونوع العملية (إيداع)، وحالتها (منتهية)، والطريقة (بطاقة)، ومعرّفات المعاملة من جهة البوابة. أجيبوا بـ200 OK في أقل من خمس ثوانٍ بجسم فارغ.
5. التحقق من العملية
بمعرّف العملية المتلقى، اقرؤوا تفاصيل العملية: نوع الإيداع، والحالة منتهية. والمبلغ الإجمالي المُرجَع هو المبلغ بعد تطبيق الرسوم والعمولات. ولا يجب أن يتغير الرصيد المعروض للمستخدم إلا بعد هذا التحقق.
صيغتان مفيدتان
| الصيغة | الغرض منها | ما الذي يتغير |
|---|---|---|
| الإيداع في محفظة وكيل | تغذية رصيد وكيل من شبكتكم | يحل رمز الوكيل محل رقم الهاتف؛ ومسار 3-D Secure هو نفسه |
| الإيداع ببطاقة محفوظة | التعبئة دون إعادة إدخال البطاقة | تسترجعون معرّف البطاقة المحفوظة، ثم تعيدون الإيداع برمز CVV والمبلغ فقط |
وتهم صيغة الوكيل الشركاء الذين يشغّلون شبكة للإيداع والسحب النقدي: إذ يمكن لوكلائهم إعادة تكوين رصيدهم دون تنقّل.
البطاقة والنقد: الجمع بين مداخل المال
ليس الإيداع بالبطاقة المدخل الوحيد للمحفظة، ولا ينبغي أن يكون كذلك. فجزء من مستخدميكم لا يملك بطاقة، أو يفضّل الأداء نقدًا. وبالنسبة إليهم، يؤدي الإيداع النقدي عبر مرجع في شبكة الوكلاء العمل نفسه: ينشئ تطبيقكم طلب إيداع يولّد مرجعًا بمدة صلاحية محدودة، ويقدّمه الزبون لوكيل، وينفّذ الوكيل العملية.
ويفضي المساران إلى النتيجة نفسها، رصيد مقيَّد ومؤكَّد عبر ويب هوك. اقترحوهما جنبًا إلى جنب في شاشة «تغذية حسابي»، مع عرض رسوم كل منهما قبل التأكيد.
وفكّروا أيضًا في مستوى حساب زبونكم. فالملف الذي تُرجعه API يبيّن مستوى KYC من 1 إلى 4، وسقوف المحفظة تتوقف على هذا المستوى: تحققوا منه قبل اقتراح إيداع كبير، ووجّهوا المستخدم إلى التحقق التكميلي عند الحاجة، بدل ترك العملية تفشل.
الممارسات الجيدة
- التأكيد على أساس العملية لا إعادة التوجيه. فالعودة من المتصفح قد تنقطع أو تُعاد أو تُزوَّر؛ والويب هوك وقراءة العملية هما المعتمدان.
- جعل المعالجة Idempotent. فدون رد 2xx، تتوالى المحاولات: بعد دقيقة، ثم 5 و30 و60 دقيقة، ثم كل ست ساعات إلى غاية 72 ساعة في المجموع. وقد يصل الإشعار نفسه إذن عدة مرات.
- تتبع كل طلب. أرسلوا
C-Request-Idفريدًا: فهو يعود في الرد وفي الإشعار، ويسهّل التواصل مع الدعم. - حماية بيانات البطاقة. فهي تمرّ عبر خادمكم لتُرسل إلى API: لا تسجلوها أبدًا، وراجعوا مع مستشاركم التزاماتكم المتعلقة بأمن بيانات البطاقات.
- شرح حالات الفشل. فرفض البنك، أو مصادقة متروكة، أو بيانات خاطئة، لا تستدعي الرسالة نفسها؛ ويساعدكم رمز السبب على التمييز بينها.
ما لا يجب الخلط بينه
الإيداع بالبطاقة يغذّي محفظة مستخدمكم. أما التاجر الذي يريد استخلاص ثمن مشتريات زبونه فيستعمل أداة أخرى: صفحة دفع مستضافة، يُدخل فيها الزبون بطاقته ويصادق بـ3-D Secure دون أن يرى التاجر رقم البطاقة أبدًا. وهذا هو دور ChariPay، منصة الدفع التي تشغّلها Chari Money؛ ويشرح دليلها حول 3-D Secure ونسب النجاح ما تغيّره المصادقة بالنسبة إلى التاجر، ويشرح دليلها حول الدفع الإلكتروني في المغرب كيفية الاستخلاص.
للتعمق أكثر
بعد وضع الإيداع بالبطاقة، يمكن استعمال رصيد المحفظة في خدمات الحياة اليومية: يبيّن دليلنا حول تعبئة الهاتف والقسائم عبر API كيفية إضافتها، ويكمّل دليل إدماج أداء الفواتير العرض.
الخطوة التالية
اطلبوا الوصول إلى sandbox من توثيق API، واطلبوا تفعيل بوابة البطاقة لحساب الشريك الخاص بكم، وجرّبوا المسار ببطاقة الاختبار. ويبقى الإطلاق في الإنتاج رهينًا بموافقة بنك المغرب، من خلال الحصول على صفة الوكيل الرئيسي، ويتطلب أي حالة استخدام جديدة الموافقة المسبقة لمديرية الإشراف البنكي.
الأسئلة الشائعة
- كيف نغذّي محفظة بالبطاقة؟
- بواسطة API الخاصة بـChari Money، على أربع مراحل: معاينة الإيداع للحصول على الرسوم، ثم تنفيذه ببيانات البطاقة، ثم جعل حامل البطاقة يُتمّ مصادقة 3-D Secure، ثم تأكيد القيد عند وصول الويب هوك وبقراءة العملية. والمحفظة التي تُقيَّد فيها الأموال هي المرتبطة برقم هاتف الزبون.
- هل 3-D Secure إلزامي؟
- في هذا المسار، يكون 3-D Secure مفعّلًا افتراضيًا. ويشير رد التنفيذ إلى ما إذا كانت إعادة التوجيه ضرورية، ويقدّم عنوان صفحة المصادقة. وبعد المصادقة، يعود حامل البطاقة إلى عنوان النجاح أو الفشل لديكم، مع رمز نتيجة يجب التحقق منه.
- هل يمكن اعتبار الإيداع ناجحًا عند العودة من إعادة التوجيه؟
- لا. تخبركم إعادة التوجيه بنتيجة المصادقة، لكن قيد المبلغ في المحفظة يتأكد عند وصول ويب هوك الإيداع بالبطاقة المأذون به وبقراءة العملية: نوع الإيداع، والحالة منتهية. وهذا التأكيد هو ما يجب أن يحدّث الرصيد المعروض.
- هل يمكن حفظ بطاقة الزبون؟
- نعم. إذا طلبتم الاحتفاظ بالبطاقة عند التنفيذ، فإنها تُحفظ في شكل رمز. وتُعاد الإيداعات اللاحقة بمعرّف البطاقة المحفوظة ورمز CVV والمبلغ، دون إعادة إرسال رقم البطاقة.
- ماذا يحدث إذا لم يُجب خادمي على الويب هوك؟
- أجيبوا بـ200 OK في أقل من خمس ثوانٍ. فأي رمز خارج 2xx يُطلق محاولة جديدة بعد دقيقة، ثم 5 و30 و60 دقيقة، ثم كل ست ساعات إلى غاية 72 ساعة في المجموع. ويجب أن تكون معالجتكم Idempotent، لأن الإشعار قد يصل عدة مرات.
- أريد استخلاص مشتريات بالبطاقة: هل هو المسار نفسه؟
- لا. فالإيداع بالبطاقة يغذّي محفظة مستخدم. ولاستخلاص مشتريات زبنائكم بصفتكم تاجرًا، تشغّل Chari Money منصة ChariPay: يؤدي الزبون في صفحة مستضافة مع 3-D Secure ولا ترون أبدًا رقم بطاقة.