مقدمة

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

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

ما الذي تبنيه

الجزء المطلوب منك صغير:

1. ينشئ خادمك عملية دفع عبر POST /api/v1/payments ويحصل على checkout_url.
2. تحوّل العميل إلى هذا الرابط. يعرض الجسر اسم تطبيقك وشعاره والمبلغ ومرجع الطلب، ثم ينقل العميل إلى صفحة البطاقة لدى المزوّد.
3. يعود العميل إلى عنوان return_url الخاص بك.
4. يتأكد خادمك من النتيجة، إما من إشعار Webhook أو بجلب الدفعة. لا تعتمد على إعادة التوجيه وحدها أبداً.

تشرح صفحة مسار الدفع ذلك خطوة بخطوة.

المفاتيح التجريبية والفعلية

لكل تطبيق نوعان من مفاتيح API:

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

الدفعات التجريبية والفعلية منفصلة: المفتاح التجريبي لا يرى الدفعات الفعلية، والعكس صحيح. وكل دفعة وكل إشعار Webhook يحمل الحقل mode.

المبالغ

المبالغ أعداد صحيحة بالدينار العراقي (IQD): القيمة 25000 تعني 25,000 دينار، بلا كسور. وتحمل كل دفعة الحقل currency، وقيمته اليوم دائماً IQD.

إلى أين بعد ذلك

• البدء السريع: أول دفعة تجريبية خلال خمس دقائق باستخدام curl.
• المصادقة: كيف ترسل مفتاحك وكيف تبدّله.
• الدفعات: كل حقول واجهة الدفعات.
• إشعارات Webhook: الأحداث والتواقيع وإعادة الإرسال.