الوضع التجريبي | توثيق جسر ألفابت

كل طلب بمفتاح تجريبي (pk_test_…) يذهب إلى محاكٍ مدمج لمزوّد الدفع. لا يصل أبداً إلى بوابة حقيقية ولا يحرّك أي أموال، أياً كان حساب المزوّد المرتبط بتطبيقك. وكل ما عدا ذلك حقيقي: تُحفظ الدفعة، وتظهر صفحة الدفع المستضافة، وتُوقَّع إشعارات Webhook وتُرسل، وتعرضها لوحات التحكم مع علامة TEST.

اختر النتيجة

أنشئ دفعة بمفتاحك التجريبي وافتح checkout_url. بعد الضغط على «ادفع»، تعرض صفحة المحاكي (وعليها علامة الوضع التجريبي) أربع نتائج بدلاً من نموذج البطاقة:

اختر	تصبح الدفعة	إشعار Webhook	يعود العميل مع
مدفوعة	`paid`	`payment.paid`	`status=paid`
مرفوضة	`failed`	`payment.failed`	`status=failed`
ملغاة	`cancelled`	`payment.cancelled`	`status=cancelled`
دعها تنتهي	`pending`، ثم `expired` عند `expires_at`	`payment.expired`	`status=pending`

تظهر الصفحة بلغة locale للدفعة (العربية أو الإنجليزية). وكل اختيار يعيد العميل عبر الجسر إلى return_url تماماً كما في الدفعة الفعلية.

خيار دعها تنتهي لا يغيّر شيئاً في المحاكي: تبقى الدفعة pending حتى expires_at (بعد 30 دقيقة من الإنشاء افتراضياً)، ثم تصبح expired ويُرسل الإشعار. وفي أثناء الانتظار يمكن للعميل أن يعود ويدفع.

ويمكنك أيضاً الإلغاء من صفحة الدفع في الجسر قبل الضغط على «ادفع»، أو الإلغاء من خادمك عبر POST /api/v1/payments/{id}/cancel.

الاسترداد

استرد دفعة تجريبية بحالة paid أو partially_refunded عبر الواجهة البرمجية:

bash

curl -s -X POST "$BRIDGE_URL/api/v1/payments/01a13c8c-8592-70f4-9ef9-d3767e74d54c/refunds" \
  -H "Authorization: Bearer $BRIDGE_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"amount": 10000, "reason": "One item out of stock"}'

الاسترداد الجزئي يجعل الدفعة partially_refunded، واسترداد الباقي يجعلها refunded، ولكل منهما إشعاره. أما الاسترداد الفعلي فيعمل بطريقة مختلفة، راجع الاسترداد.

ما يبقى كما هو في الوضع الفعلي

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

ما يختلف في الوضع الفعلي

يدفع العميل ببطاقة حقيقية في صفحة المزوّد.
يجب أن يبدأ return_url بـ https://.
يُطلب الاسترداد من لوحة التحكم، ونقطة الاسترداد في الواجهة البرمجية ترد بـ 422 refunds_processed_manually.
الدفعات التجريبية لا تُحتسب أبداً في الأرصدة أو التسويات.

الانتقال إلى الوضع الفعلي

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