PesaBridge
التوثيق/البداية/البدء السريع: دفعتك الأولى

البداية

البدء السريع: دفعتك الأولى

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

5 دقائق قراءة

في هذه الصفحة
  1. قبل أن تبدأ
  2. 1. احصل على رمز وصول
  3. 2. أخبرنا أين نرسل النتائج
  4. 3. أرسل طلب دفع
  5. 4. استقبل النتيجة
  6. 5. أو تحقق من الحالة بنفسك
  7. الخطوات التالية

قبل أن تبدأ

أنشئ حساب مطور مجانيًا على pesa-bridge.com/developer/signup. تحصل فورًا على مجموعتي مفاتيح: pk_test_… / sk_test_… لبيئة الاختبار وpk_… / sk_… للإنتاج. المفتاح الذي تصادق به هو الذي يحدد الوضع، لذا لا تمس حركة الاختبار أموالًا حقيقية أبدًا.

كل استدعاء في هذا الدليل يذهب إلى عنوان أساسي واحد:

العنوان الأساسي
https://pesa-bridge.com/api/bridgepay/v1

1. احصل على رمز وصول

استبدل زوج مفاتيحك برمز Bearer. تدوم الرموز ساعة واحدة، فاطلب رمزًا جديدًا قبل انتهاء expires_in.

الطلب
curl -s https://pesa-bridge.com/api/bridgepay/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"pk_test_…","client_secret":"sk_test_…"}'
الاستجابة
{
  "access_token": "at_9f3…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "mode": "test",
  "sandbox": true
}

2. أخبرنا أين نرسل النتائج

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

Shell
curl -s https://pesa-bridge.com/api/bridgepay/v1/partner/webhooks/endpoints \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Orders","url":"https://your-app.com/webhook","events":"*","mode":"test"}'
لا يوجد لديك خادم عام بعد؟ استخدم المستقبِل المدمج PesaBridge Echo: يعيد GET /partner/echo/url عنوانًا يلتقط التسليمات ويتحقق من تواقيعها، ويمكنك فحصها في وحدة تحكم المطور.

3. أرسل طلب دفع

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

الطلب
curl -s https://pesa-bridge.com/api/bridgepay/v1/partner/stk \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"payer_msisdn":"254708374149","amount":250,"reference":"INV-1001","idem":"inv-1001-1"}'
الاستجابة
{
  "charge_ref": "STK0000123",
  "state": "pending",
  "amount": 250.0,
  "expiry": "2026-09-27T12:05:00Z"
}

يوافق العميل على هاتفه الخاص برقمه السري. أنت لا تراه ولا تتعامل معه أبدًا.

4. استقبل النتيجة

عند اكتمال الخصم نرسل بطريقة POST حدثًا موقعًا إلى نقطة النهاية لديك:

HTTP
POST /webhook
X-PesaBridge-Event: charge.completed
X-PesaBridge-Signature: …e9 (hex HMAC-SHA256 of the raw body)

{
  "event": "charge.completed",
  "charge_ref": "STK0000123",
  "reference": "INV-1001",
  "amount": 250.0,
  "currency": "KES",
  "payer": "254708374149",
  "state": "completed",
  "transaction": "PB7H2K9Qmn"
}

تحقق من التوقيع، وضع علامة «مدفوع» على الطلب، وأجب بأي رمز 2xx. راجع Webhooks للاطلاع على شيفرة التحقق بعدة لغات.

5. أو تحقق من الحالة بنفسك

تبقى رسائل webhook المرجع المعتمد، لكن يمكنك السؤال في أي وقت:

Shell
curl -s "https://pesa-bridge.com/api/bridgepay/v1/partner/status?charge_ref=STK0000123" -H "Authorization: Bearer $TOKEN"
JSON
{ "charge_ref": "STK0000123", "state": "completed", "transaction": "PB7H2K9Qmn" }

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

التالي المصادقة

يجيب مهندسونا عن أسئلة الربط. أرسل إلينا مرجع الطلب وسنجد الاستدعاء بالضبط.

تواصل مع الدعم