مرجع API الـ Payment Intents

مرجع كامل لنقاط نهاية API الـ Payment Intents.

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

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

إصدار API موجود في المسار (v1). لاستخدام إصدار آخر، استخدم الرابط الأساسي المقابل (مثل https://api.orcarail.com/api/v2). تستخدم Node SDK الإعدادين baseUrl وapiVersion؛ راجع Node SDK.

إنشاء Payment Intent

أنشئ Payment Intent جديدًا.

POST /payment_intents

المصادقة

• رمز Bearer (JWT) أو مفتاح API (Basic Auth)

جسم الطلب

المعامل	النوع	مطلوب	الوصف
amount	string	نعم	المبلغ المطلوب تحصيله (مثل "100.00")
currency	string	نعم	رمز العملة (مثل "usd")
payment_method_types	array	نعم	يجب أن يتضمن "crypto"
tokenId	number	نعم	معرّف الرمز (مثل USDC وUSDT)
networkId	number	نعم	معرّف الشبكة (مثل Ethereum وPolygon)
return_url	string	نعم	رابط العودة بعد الدفع
cancel_url	string	لا	رابط الإلغاء
description	string	لا	وصف الدفعة
metadata	object	لا	بيانات وصفية مخصصة
expires_at	string	لا	طابع انتهاء الصلاحية بصيغة ISO 8601
withdrawal_addresses	object	لا	عناوين السحب حسب نوع الشبكة. المفاتيح: أنواع الشبكات الصالحة (evm وsolana وbitcoin وtron وcosmos وpolkadot وmove وton). احذفه أو اتركه فارغًا لشبكة ما لاستخدام الافتراضي في حسابك من إعدادات السحب.

الاستجابة

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "100.00",
  "currency": "usd",
  "status": "requires_payment_method",
  "paymentMethodTypes": ["crypto"],
  "clientSecret": "550e8400-e29b-41d4-a716-446655440000_secret_abc123",
  "returnUrl": "https://merchant.example.com/return",
  "paymentLink": {
    "id": 1,
    "link": "https://pay.orcarail.com/pay/pl_abc123"
  },
  "createdAt": "2024-01-01T00:00:00.000Z"
}

استرجاع Payment Intent

احصل على تفاصيل Payment Intent.

GET /payment_intents/:id

المصادقة

• رمز Bearer (JWT) أو مفتاح API (Basic Auth)

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

المعامل	النوع	مطلوب	الوصف
id	string	نعم	معرّف الـ Payment Intent (مثل 550e8400-e29b-41d4-a716-446655440000)

الاستجابة

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "100.00",
  "currency": "usd",
  "status": "succeeded",
  "paymentMethodTypes": ["crypto"],
  "latestTransaction": {
    "id": "txn_1234567890",
    "status": "completed",
    "hash": "0x1234567890abcdef...",
    "amount": "100.00"
  },
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

تأكيد Payment Intent

أكّد Payment Intent للحصول على رابط التوجيه.

POST /payment_intents/:id/confirm

المصادقة

• رمز Bearer (JWT) أو مفتاح API (Basic Auth)

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

المعامل	النوع	مطلوب	الوصف
id	string	نعم	معرّف الـ Payment Intent

جسم الطلب

المعامل	النوع	مطلوب	الوصف
client_secret	string	نعم	الـ client secret من الـ Payment Intent
return_url	string	لا	تجاوز رابط العودة
payment_method_data	object	لا	بيانات طريقة الدفع

الاستجابة

{
  "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"
    }
  }
}

إلغاء Payment Intent

ألغِ Payment Intent. بعد إلغائه لا يمكن استخدامه للدفع.

POST /payment_intents/:id/cancel

المصادقة

• مفتاح API (Basic Auth) — مطلوب

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

المعامل	النوع	مطلوب	الوصف
id	string	نعم	معرّف الـ Payment Intent

الاستجابة

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

إكمال Payment Intent

علّم Payment Intent بأنه قيد المعالجة وأطلق الـ webhook payment_intent.processing. استدعِ ذلك بعد عودة العميل إلى رابط العودة (مثل صفحة النجاح) ليعلّم خادمك الخلفي الـ intent بأنه قيد المعالجة بينما تستطلع أو تنتظر الـ webhook النهائي payment_intent.complete.

POST /payment_intents/:id/complete

المصادقة

• مفتاح API (Basic Auth) — مطلوب

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

المعامل	النوع	مطلوب	الوصف
id	string	نعم	معرّف الـ Payment Intent

الاستجابة

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

محاكاة دفعة (للـ sandbox فقط)

أكمل Payment Intent دون تحويل على السلسلة، في مؤسسة sandbox فقط. تمر الدفعة بالتدفق العادي وتُطلق الـ webhooks المعتادة مع livemode: false، وتحمل معاملتها simulated: true. المدفوعات المحاكاة غير قابلة للسحب أبدًا.

POST /payment_intents/:id/simulate

المصادقة

• مفتاح API (Basic Auth) لمؤسسة sandbox (ak_test_…) — مطلوب

الأخطاء

الحالة	الرمز	متى
403	SIMULATION_SANDBOX_ONLY	ينتمي الـ intent إلى مؤسسة حية

تستخدم صفحة الدفع المستضافة المقابل العام POST /payments/links/:slug/simulate (لروابط الـ sandbox فقط).

تحديث Payment Intent

حدّث Payment Intent قبل التأكيد.

PATCH /payment_intents/:id

المصادقة

• رمز Bearer (JWT) أو مفتاح API (Basic Auth)

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

المعامل	النوع	مطلوب	الوصف
id	string	نعم	معرّف الـ Payment Intent

جسم الطلب

كل الحقول اختيارية. ضمّن فقط الحقول المراد تحديثها.

المعامل	النوع	مطلوب	الوصف
amount	string	لا	المبلغ المحدّث
currency	string	لا	العملة المحدّثة
description	string	لا	الوصف المحدّث
metadata	object	لا	البيانات الوصفية المحدّثة
return_url	string	لا	رابط العودة المحدّث
cancel_url	string	لا	رابط الإلغاء المحدّث
withdrawal_addresses	object	لا	عناوين السحب حسب نوع الشبكة؛ احذفه لاستخدام الافتراضي في الحساب

الاستجابة

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "150.00",
  "currency": "usd",
  "status": "requires_payment_method",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

رموز الحالة

رمز الحالة	الوصف
200	نجاح
201	تم الإنشاء
400	طلب غير صالح
401	غير مصرّح
404	غير موجود
500	خطأ داخلي في الخادم

صيغة استجابة الخطأ

{
  "statusCode": 400,
  "message": "Invalid request",
  "error": "Bad Request"
}

حدود المعدل

تخضع طلبات API لحدود معدل. الحدود الحالية:

• الطلبات المصادَق عليها: 100 طلب في الدقيقة لكل مفتاح API/مستخدم
• الطلبات غير المصادَق عليها: 10 طلبات في الدقيقة لكل IP

تتضمن الاستجابات ترويسات حدود المعدل:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

انظر أيضًا

• دليل Payment Intents — أدلة مفصّلة
• الـ webhooks — استقبل إشعارات الدفع