مسار الدفع

تمر الدفعة بأربعة أطراف: خادمك، ومتصفح العميل، والجسر، ومزوّد الدفع (APS اليوم، أو المحاكي في الوضع التجريبي). تتبع هذه الصفحة دفعة واحدة من بدايتها إلى نهايتها.

الخطوات

1. ينشئ خادمك الدفعة. عبر POST /api/v1/payments بالمبلغ ومرجع طلبك order_reference، ومعه return_url إن شئت. يفتح الجسر الدفعة لدى المزوّد ويرد بـ 201 ودفعة بحالة pending ومعها checkout_url.

2. تحوّل العميل إلى checkout_url. تعرض صفحة الدفع المستضافة اسم تطبيقك وشعاره والمبلغ بالدينار ومرجع الطلب، بالعربية أو الإنجليزية (حسب locale في الدفعة، أو اختيار العميل في الصفحة). يضغط العميل «ادفع» أو يلغي.

3. يدفع العميل في صفحة المزوّد. ينقل الجسر العميل إلى صفحة البطاقة الآمنة لدى المزوّد، فلا تمر بيانات البطاقة أبداً عبر الجسر أو عبر تطبيقك.

4. يعود العميل عبر الجسر. يعيد المزوّد العميل إلى الجسر، فيسأل الجسر المزوّد عن النتيجة فوراً. وإن لم يحسم المزوّد النتيجة بعد، يرى العميل صفحة قصيرة «جارٍ تأكيد الدفع» تعيد التحقق كل 3 ثوانٍ لنحو 30 ثانية.

5. يحوّل الجسر العميل إلى return_url مع إضافة payment_id وstatus وorder_reference إلى الرابط:

   text

   https://shop.example/return?payment_id=01a13c8c-8592-70f4-9ef9-d3767e74d54c&status=paid&order_reference=ORD-1001
   

   إن كان في return_url استعلام مسبق، تُضاف هذه المعاملات إليه.

6. يتأكد خادمك. إما أن يستقبل عنوان Webhook الخاص بك الحدث payment.paid (أو غيره)، أو يستدعي خادمك GET /api/v1/payments/{id}. بعد ذلك فقط تسلّم الطلب.

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

لا تعتمد على إعادة التوجيه وحدها

الاستعلام المضاف إلى return_url يكتبه متصفح العميل، وأي شخص يستطيع كتابة status=paid في شريط العنوان. استخدمه فقط لاختيار ما تعرضه في الصفحة («شكراً لك»، «فشل الدفع»). وقبل أن تشحن أي شيء، تأكد من الحالة على خادمك عبر إشعار Webhook موثّق التوقيع أو عبر GET /api/v1/payments/{id}.

إعادة التوجيه بـ status=pending تعني أن المزوّد لم يرد خلال نحو 30 ثانية. أخبر العميل أن الدفعة قيد التحقق، وسيصلك إشعار Webhook عند حسمها.

عندما لا يدفع العميل

• يلغي من صفحة الدفع: تصبح الدفعة cancelled ويعود العميل إلى return_url مع status=cancelled.
• تُرفض البطاقة: تصبح الدفعة failed.
• لا يدفع أحد في الوقت المحدد: تنتهي الدفعة غير المدفوعة بعد 30 دقيقة افتراضياً (ويمكن لألفابت تغيير المدة لكل تطبيق). تصبح expired، ورابط الدفع المنتهي يعيد العميل إلى return_url.
• يلغيها خادمك: عبر POST /api/v1/payments/{id}/cancel ما دامت pending.

كل حالة من هذه ترسل إشعار Webhook. ولإعادة المحاولة أنشئ دفعة جديدة، إذ يمكن إعادة استخدام order_reference نفسه بعد أن تصبح الدفعة السابقة failed أو cancelled أو expired.

الدفعة الملغاة قد تصبح مدفوعة

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

إن أبلغ المزوّد خلال هذه المدة أن الدفعة مدفوعة، تنتقل إلى paid ويصلك الحدث payment.paid كأي دفعة أخرى. وبما أن مال العميل قد اقتُطع، فعلى تطبيقك عندها أن يسلّم الطلب أو يسترد المبلغ. أما الدفعات التي رفضها المزوّد نفسه أو انتهت لديه فهي نهائية ولا تتغير بعد ذلك.

من يخبرك بماذا