مرجع API الدفع

مرجع كامل لنقاط نهاية API الدفع. استخدمها عندما يكون لديك slug لرابط دفع وتريد الحصول على تفاصيل الدفع أو تأكيده أو إلغاءه.

الرابط الأساسي

https://api.orcarail.com/api/v1

الحصول على الدفع حسب الـ slug

احصل على تفاصيل الدفع لرابط دفع عبر الـ slug الخاص به. لا تتطلب مصادقة؛ استخدمها لعرض معلومات الدفع قبل أن يدفع العميل.

GET /pay/:slug

معاملات المسار

المعامل	النوع	مطلوب	الوصف
slug	string	نعم	slug رابط الدفع (مثل pl_abc123)

الاستجابة

تعيد تفاصيل الدفع بما فيها المبلغ والرمز والشبكة وأي بيانات وصفية لازمة لعرض صفحة الدفع.

{
  "id": 1,
  "title": "Payment for services",
  "slug": "pl_abc123",
  "amount": "0.1",
  "tokenId": 1,
  "networkId": 1,
  "status": "active",
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "metadata": {},
  "createdAt": "2024-01-01T00:00:00.000Z"
}

تأكيد الدفع

أكّد payment intent عبر الـ slug واحصل على رابط التوجيه إلى تطبيق الدفع المستضاف. قد يستخدم الطلب ترويسة Origin أو Referer لتحديد أصل الواجهة الأمامية في رابط العودة.

POST /pay/:slug/confirm

معاملات المسار

المعامل	النوع	مطلوب	الوصف
slug	string	نعم	slug رابط الدفع

الترويسات

الترويسة	النوع	مطلوبة	الوصف
Origin	string	لا	أصل الواجهة الأمامية (يُستخدم لرابط العودة)
Referer	string	لا	بديل عن Origin لأصل الواجهة الأمامية

الاستجابة

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "requires_confirmation",
  "nextAction": {
    "type": "redirect_to_url",
    "redirectToUrl": {
      "url": "https://pay.orcarail.com/pay/pl_abc123?payment_intent=550e8400-e29b-41d4-a716-446655440000&payment_intent_client_secret=550e8400-e29b-41d4-a716-446655440000_secret_abc123"
    }
  }
}

وجّه العميل إلى nextAction.redirectToUrl.url لإكمال الدفع في صفحة الدفع المستضافة.

إلغاء الدفع

ألغِ الـ payment intent المرتبط بـ slug رابط الدفع.

POST /pay/:slug/cancel

معاملات المسار

المعامل	النوع	مطلوب	الوصف
slug	string	نعم	slug رابط الدفع

الاستجابة

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "canceled",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

حالات الاستخدام

1. الحصول على الدفع — استدعِ GET /pay/:slug لعرض المبلغ والرمز والشبكة في صفحتك.
2. بدء الدفع — استدعِ POST /pay/:slug/confirm ووجّه المستخدم إلى الرابط المُعاد.
3. الإلغاء — استدعِ POST /pay/:slug/cancel إذا ترك المستخدم الدفع أو احتجت إلى إلغاء الـ intent.

رموز الحالة

رمز الحالة	الوصف
200	نجاح
400	طلب غير صالح
404	غير موجود (slug غير صالح)
500	خطأ داخلي في الخادم

انظر أيضًا

• Payment Intents — أنشئ الـ payment intents وأدِرها حسب المعرّف
• المدفوعات — روابط الدفع والمعاملات
• الـ webhooks — استقبل أحداث الدفع