كيفية إنشاء رابط دفع: كل إعداد خطوة بخطوة، من بوابة التاجر إلى API

كيفية إنشاء رابط دفع لا تتطلب إلا إعدادات قليلة: مبلغ بالدرهم، ووصف، ومدة صلاحية، ثم، إن شئتم، زبون مسجَّل وخيار «Paiement en agence» (الأداء في الوكالة)؛ أما الرابط القابل لإعادة الاستعمال فيُنشأ عبر API. وتعيد لكم بوابة التاجر في ChariPay رابطًا لاستعمال واحد تشاركونه — في رسالة أو بالبريد الإلكتروني أو برمز QR أو بملصق — وتخبركم حين يُؤدّى. يستعرض هذا الدليل كل إعداد، من بوابة التاجر إلى API: ماذا يفعل، ومتى تختارونه، والأخطاء التي تكلّف أداءً مزدوجًا أو زبونًا ضائعًا، والنداء الواحد الذي ينشئ الرابط نفسه من شفرتكم دون أن ينشئه مرتين أبدًا.

إنشاء رابط دفع: ما تحتاجونه قبل البدء

رابط الدفع مبلغ ووصف؛ يدفع الزبون في صفحة تستضيفها ChariPay. وChariPay منصة دفع مغربية، مزوّد خدمات دفع (PSP) تشغّله Chari Money، مؤسسة أداء مرخَّصة من بنك المغرب. ولإنشاء رابط، لا تحتاجون إلى موقع ويب ولا إلى مطوّر: يكفي الوصول إلى بوابة التاجر.

ولتطبيق هذا الدليل وأنتم تقرؤونه، يكفي حساب في وضع الاختبار. يُفتح وضع الاختبار بمجرد تفعيل حسابكم، دون موافقة تنتظرونها: ابدؤوا في وضع الاختبار — ثلاثة حقول (الاسم، والبريد الإلكتروني المهني، والمؤسسة)، ورابط تفعيل يصلكم بالبريد لاختيار كلمة المرور، ثم بوابة التاجر حيث تنشئون بأنفسكم مفتاح الاختبار بعد إعادة مصادقة؛ ولا يُعرض المفتاح كاملًا إلا مرة واحدة. ادفعوا روابط الاختبار ببطاقة الاختبار ‎4918 9141 0719 5005، CVV 123، وأي تاريخ انتهاء مستقبلي، ورمز ‎3-D Secure 555: هذه البطاقة هي الوحيدة المقبولة، ولا يتحرك أي مال حقيقي. ويجري التحقق من مؤسستكم (KYB) بالتوازي ولا يشترطه إلا الانتقال إلى الإنتاج. ووضع الاختبار مجاني، بلا حد زمني وبلا التزام.

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

إنشاء رابط دفع في بوابة التاجر خطوة بخطوة

في بوابة التاجر، ينطلق كل شيء من شاشة «روابط الدفع»، التي تعرض الروابط المنشأة سابقًا مع حالتها.

1. 1افتحوا روابط الدفع في بوابة التاجر وابدؤوا إنشاء رابط جديد.
2. 2أدخلوا المبلغ بالدرهم (MAD) والوصف الذي سيقرؤه الزبون في الصفحة: موضوع البيع ومرجعكم الداخلي.
3. 3احتفظوا بالاستعمال الواحد لبيعة بعينها: يُستهلك الرابط بعد أداء ناجح واحد. أما الرابط القابل لإعادة الاستعمال، لمبلغ واحد يؤدّيه عدة زبناء، فنعرضه أدناه.
4. 4اختاروا مدة الصلاحية: 24 ساعة، 7 أيام، 30 يومًا، بلا انتهاء، أو تاريخ محدد.
5. 5اربطوا زبونًا مسجَّلًا إن شئتم: فتجدون معلوماته من جديد في روابطكم القادمة.
6. 6فعّلوا خيار «Paiement en agence» (الأداء في الوكالة) إن كنتم تعلمون أن الزبون سيؤدّي نقدًا: يعطّل هذا الخيار مدة صلاحية الرابط، فيبقى قابلًا للأداء بلا حدّ زمني؛ فالرابط الذي يحمل تاريخ انتهاء يُقدَّم إذن كرابط يُؤدّى بالبطاقة.
7. 7أنشئوا الرابط وانسخوه، أو اعرضوا رمز QR الخاص به، لمشاركته.

يظهر الرابط الجديد في القائمة بحالة «نشط». وكل شيء بالدرهم المغربي (MAD): المستخلصات، والأرصدة، والتحويلات، والدفعات نحو البنك، دون أي تحويل للعملة. وإن أخطأتم في المبلغ قبل الأداء، فلا ترتجلوا: ألغوا هذا الرابط وأنشئوا رابطًا جديدًا.

إعدادات الرابط حقلًا حقلًا

ويستحق الوصف عناية أكبر مما يُمنح له عادة. فالزبون يقرؤه لحظة الأداء: «الطلبية 1042 — علبتا هدايا» يطمئنه أكثر من عنوان مبهم. وبه تجدون الرابط في بوابة التاجر، ثم الحركة في تصديراتكم. وقاعدة بسيطة تصلح طويلًا: موضوع البيع، ثم رقم الطلبية أو عرض الأثمان أو الفاتورة.

لاستعمال واحد أم قابل لإعادة الاستعمال: ما الذي يغيّره الاختيار

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

أما الرابط القابل لإعادة الاستعمال فيحمل ثمنًا: المبلغ نفسه، يؤدّيه من شاء من الزبناء إلى انتهاء صلاحيته أو إلغائه — اشتراك، أو تذكرة، أو منتج يكثر عليه الطلب. وهو يستخلص بالبطاقة وحدها. إنه الرابط الذي يوضع على ملصق، أو في نبذة حساب على شبكة اجتماعية، أو في صفحة من موقعكم. من بوابة التاجر، كل رابط دفع تنشئونه هو رابط لاستعمال واحد. أما الرابط القابل لإعادة الاستعمال — مبلغ واحد يؤدّيه عدة زبناء — فيُنشأ عبر API بـsingleUse: false؛ وبعد إنشائه يظهر في بوابة التاجر كباقي الروابط. ومن دون مطوّر، للبيع مرات عديدة بالسعر نفسه، انشروا منتجًا في متجركم المستضاف وشاركوا رابطه.

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

مشاركة الرابط حيث يقرؤكم زبونكم

يُشارَك الرابط كرابط أو رمز QR أو ملصق PDF للطباعة أو بالبريد الإلكتروني أو واتساب. اختاروا القناة التي تُحسم فيها البيعة أصلًا:

• رابط للنسخ: في محادثة واتساب، أو رسالة خاصة، أو رسالة SMS، أو بريد إلكتروني تكتبونه بأنفسكم. ورسالة SMS فعلكم أنتم: لا ترسل ChariPay رابط الدفع الخاص بكم لا عبر SMS ولا عبر واتساب.
• البريد الإلكتروني: من بوابة التاجر، أو عبر API بالنداء POST /v1/payment-links/{reference}/send، الذي يجيب بـ202 ويرسل الرابط إلى الزبون المسجَّل أو إلى العنوان الذي تحدّدونه.
• رمز QR وملصق PDF: لنقطة البيع، أو رواق في معرض، أو وثيقة مطبوعة. وتجدون طريقة استعمالهما — أين تضعونهما، وأي رابط تطبعون — في دليل الدفع عبر رمز QR.

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

تتبّع الرابط وإلغاؤه وتخصيصه

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

ولإلغاء رابط، استعملوا بوابة التاجر، أو API بالنداء POST /v1/payment-links/{reference}/cancel. فالرابط الملغى لا يمكن أداؤه: ألغوا دائمًا الرابط القديم قبل إرسال آخر للبيعة نفسها.

ومن جهة الزبون، تعرض صفحة الرابط اسمكم وشعاركم، وتُضبط من إعدادات حسابكم.

إنشاء الرابط نفسه عبر API

نداء واحد يكفي: يعيد POST /v1/payment-links عنوان payUrl لمشاركته. والقاعدة واحدة، https://api-psp.charipay.ma، في الاختبار كما في الإنتاج: المفتاح هو ما يحدّد البيئة. ومبالغ API بالوحدات الرئيسية (149.90 = 149,90 درهمًا).

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" }
  }'

يحمل الرد 201 — أو 200 إن كان رابط موجودًا سلفًا بهذا externalId — مرجع الرابط reference (pl_…) وعنوانه payUrl، أي العنوان الذي ترسلونه إلى الزبون. ولرابط قابل لإعادة الاستعمال، اجعلوا singleUse على false: فيستخلص حينها بالبطاقة وحدها. أما metadata، وهو كائن مسطَّح، فيعود إليكم كما هو عند قراءة الرابط وفي حدث الأداء: وبه يجد نظامكم الطلبية من جديد.

ولرابط يُؤدّى نقدًا، أضيفوا paymentMethod: "CASH" وأبقوا singleUse على true:

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-1043-link' \
  -d '{
    "amount": 320.00,
    "description": "Commande #1043",
    "singleUse": true,
    "paymentMethod": "CASH",
    "externalId": "order-1043",
    "customerPhone": "+212600000000",
    "metadata": { "orderNumber": "1043" }
  }'

ولا يظهر الرمز الذي يُقدَّم في الوكالة (cashinCode) ولا جهة الإيداع (cashinEntity) في ردّ الإنشاء: فهما يُنشآن عند أول فتح لصفحة الدفع، ثم يُقرآن عبر GET /v1/payment-links/{reference}. وفي هذه القراءة، قارنوا status بالقيمة "ACTIVE" لتعرفوا هل ما زال الرابط مفتوحًا، واقرؤوا useCount وtotalCollected لتعرفوا ما استخلصه. أما النداءات الأخرى — القائمة، والإلغاء، والإرسال، ورمز QR، والملصق — فتصفها وحدة «روابط الدفع» في توثيق API.

لا تنشئوا الرابط نفسه مرتين أبدًا

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

• الحقل `externalId`: معرّفكم، فريد لكل حساب ولكل بيئة. والإنشاء بـexternalId موجود سلفًا يعيد المورد الموجود بالرد 200 OK بدل 201 Created. وكلاهما نجاح: افحصوا الحالة، ولا تعاملوا 200 كخطأ.
• الترويسة `Idempotency-Key`: إعادة القيمة نفسها تعيد النتيجة الأولى؛ والمفتاح نفسه مع محتوى مختلف يعيد 409 IDEMPOTENCY_CONFLICT. وهو محصور في الحساب: احتفظوا بمفاتيح مختلفة بين السندبوكس والإنتاج.

والنتيجة العملية: externalId سبق استعماله سيعيد لكم دائمًا الرابط نفسه، ولو كان منتهي الصلاحية أو ملغى. ولرابط جديد على الطلبية نفسها، أعطوه externalId جديدًا (order-1042-2 مثلًا). ويشرح مقالنا عن Idempotency في المدفوعات المبدأ وحدوده.

أسئلة شائعة

كيف أنشئ رابط دفع يُؤدّى نقدًا؟

أنشئوا رابطًا لاستعمال واحد بخيار «Paiement en agence» في بوابة التاجر — دون مدة صلاحية —، أو عبر API بـpaymentMethod: "CASH" مع إبقاء singleUse على true. يتلقى الزبون مرجعًا في الصفحة، ويسدّده في وكالة من شبكة Chari، ويصبح الرابط «مدفوعًا» بمجرد أن تؤكد الشبكة الإيداع. أما الرابط القابل لإعادة الاستعمال، فلا يقبل إلا البطاقة.

ما مدة الصلاحية التي أختارها لرابط الدفع؟

تلك التي تطابق عرضكم. 24 ساعة لبيعة حُسمت في محادثة، و7 أو 30 يومًا لعرض أثمان أو فاتورة، وتاريخ محدد لعرض موسمي، وبلا انتهاء لملصق دائم. وبعد انقضاء الصلاحية تُخبر الصفحة الزبون بأن العرض لم يعد متاحًا، ولا يمكن لأي أداء أن يمرّ: فإن كان لا يزال يريد الشراء، أنشئوا رابطًا جديدًا.

كيف أعرف أن رابط الدفع قد أُدّي؟

عند الاستخلاص يصلكم الإشعار في بوابة التاجر ويصبح الرابط لاستعمال واحد «مدفوعًا». وعبر API، يعيد GET /v1/payment-links/{reference} من بين ما يعيده useCount وtotalCollected، ويعيد إليكم حدث الأداء بالبطاقة metadata الخاص بكم. ولا تعتمدوا أبدًا على لقطة شاشة يرسلها الزبون: فحالة الرابط وحدها، في بوابة التاجر أو عبر API، هي المعتمدة.

كيف ألغي رابط دفع سبق إرساله؟

من بوابة التاجر، أو عبر API بالنداء POST /v1/payment-links/{reference}/cancel. فالرابط الملغى لا يمكن أداؤه، ولو بقي في محادثة الزبون: إن فتحه فلن يستطيع الأداء. أخبروه بذلك، وأرسلوا إليه الرابط الجديد إن استمرت البيعة. وألغوا دائمًا الرابط القديم قبل إرسال آخر للبيعة نفسها، حتى لا يبقى أمامه رابطان.

هل يمكن تسجيل زبون لإرسال روابط أخرى إليه؟

نعم. سجّلوا زبناءكم ومعلومات الاتصال بهم في بوابة التاجر: ثم تربطونهم بروابطكم القادمة دون إعادة إدخال أي شيء. وعبر API، يحمل الرابط أيضًا customerName وcustomerEmail وcustomerPhone. ويُستعمل البريد الإلكتروني المسجَّل خصوصًا عند إرسال الرابط بـPOST /v1/payment-links/{reference}/send إن لم تحدّدوا عنوانًا آخر.

هل يمكن عرض شعاري في صفحة الدفع؟

نعم. تعرض صفحة الرابط اسمكم وشعاركم، ويُضبط ذلك من إعدادات حسابكم. فيرى زبونكم، في صفحة تستضيفها ChariPay، المتجر الذي يؤدّي له، والمبلغ والوصف، قبل أن يُدخل بطاقته ويؤكد العملية عبر ‎3-D Secure لدى بنكه، وهو ما يطمئن زبونًا وصله الرابط في رسالة.

هل يمكن إنشاء رابط دفع عبر API؟

نعم: نداء واحد يكفي، إذ يعيد POST /v1/payment-links عنوان payUrl لمشاركته. والحقلان الإلزاميان هما amount وdescription؛ أما singleUse وpaymentMethod وexpiresAt ومعلومات الزبون وexternalId وmetadata فاختيارية. ومفتاح الاختبار chari_sk_test_… ينشئ روابط اختبار تُؤدّى ببطاقة الاختبار، على القاعدة نفسها https://api-psp.charipay.ma، وهي القاعدة نفسها في الإنتاج: فالمفتاح وحده يحدّد البيئة.

ماذا يحدث إن أُرسل طلب إنشاء الرابط نفسه مرتين؟

مع externalId نفسه، يعيد الإنشاء الثاني الرابط الموجود بالرد 200 OK بدل 201 Created: فلا يُنشأ أي تكرار. ومع Idempotency-Key نفسه، تُعاد النتيجة الأولى؛ والمفتاح نفسه مع محتوى مختلف يعيد 409 IDEMPOTENCY_CONFLICT. ودون أي منهما، يُنشأ رابطان مختلفان، وقد يتلقى زبونكم الرابطين معًا.

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

افتحوا حساب الاختبار — ابدؤوا في وضع الاختبار — وأنشئوا أول رابط في بوابة التاجر وادفعوه ببطاقة الاختبار، ثم أنشئوا الرابط نفسه عبر API بمفتاح الاختبار وexternalId. وللمضي أبعد، اطبعوا رمز QR الخاص به مع دليل الدفع عبر رمز QR، أو بيعوا في المحادثات بطريقتنا في البيع عبر إنستغرام وواتساب.