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

تأخذك هذه الصفحة في دفعة تجريبية من إنشائها حتى تصبح مدفوعة، باستخدام curl ومتصفح فقط. لا تتحرك أي أموال حقيقية، فالمفتاح التجريبي لا يصل إلا إلى المحاكي المدمج.

1. احصل على مفتاح تجريبي

ينشئ مالك تطبيقك المفاتيح من لوحة تحكم التطبيق، ضمن «مفاتيح API»، ويمكن لفريق ألفابت أيضاً إصدار مفتاح لك. يبدو المفتاح التجريبي هكذا pk_test_a1B2c3D4e5F6_… ويظهر مرة واحدة فقط، فانسخه فور ظهوره.

ضع عنوان الجسر ومفتاحك في متغيرين:

bash

export BRIDGE_URL="https://<your-bridge-domain>"
export BRIDGE_KEY="pk_test_..."

2. أنشئ عملية دفع

bash

curl -s -X POST "$BRIDGE_URL/api/v1/payments" \
  -H "Authorization: Bearer $BRIDGE_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"amount": 25000, "currency": "IQD", "order_reference": "ORD-1001", "description": "Two coffees", "return_url": "https://shop.example/return"}'

يرد الجسر بـ 201 Created ومعه الدفعة:

json

{
  "id": "01a13c8c-8592-70f4-9ef9-d3767e74d54c",
  "status": "pending",
  "mode": "test",
  "amount": 25000,
  "refunded_amount": 0,
  "currency": "IQD",
  "method": "aps_card",
  "order_reference": "ORD-1001",
  "description": "Two coffees",
  "customer": {"name": null, "phone": null, "email": null},
  "payer": {"name": null, "phone": null, "email": null, "ip": "203.0.113.10", "user_agent": "curl/8.7.1"},
  "locale": "en",
  "return_url": "https://shop.example/return",
  "metadata": null,
  "checkout_url": "https://<your-bridge-domain>/checkout/01a13c8c-8592-70f4-9ef9-d3767e74d54c",
  "expires_at": "2026-10-14T23:03:24+00:00",
  "paid_at": null,
  "created_at": "2026-10-14T22:33:24+00:00",
  "refunds": []
}

احتفظ بقيمة id. لا يمكن دفع order_reference نفسه مرتين، فغيّره (ORD-1002، …) في كل مرة تعيد فيها تنفيذ الأمر.

3. ادفع من صفحة الدفع

افتح checkout_url في المتصفح واضغط «ادفع». في الوضع التجريبي تصل إلى صفحة الدفع في المحاكي، وعليها علامة الوضع التجريبي، وتسألك عن النتيجة المطلوبة. اختر مدفوعة.

يعيدك المحاكي عبر الجسر، فيتحقق الجسر من النتيجة ثم يحوّلك إلى return_url والنتيجة مضافة إلى الرابط:

text

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

4. تأكد من الدفعة

إعادة التوجيه مجرد تلميح لصفحتك. تأكد من خادمك:

bash

curl -s "$BRIDGE_URL/api/v1/payments/01a13c8c-8592-70f4-9ef9-d3767e74d54c" \
  -H "Authorization: Bearer $BRIDGE_KEY" \
  -H "Accept: application/json"

يأتي الرد بالدفعة نفسها، وقد أصبحت "status": "paid" ومعها وقت paid_at. عندها فقط سلّم الطلب.

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

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