إنشاء Payment Intent

أنشئ Payment Intent لبدء تحصيل دفعة من عميل.

نقطة النهاية

POST /api/v1/payment_intents

إصدار API موجود في مسار الرابط (v1). لا يوجد حقل إصدار في جسم الطلب.

إصدار API والـ SDK

• الإصدار في الرابط: يتضمن المسار الأساسي الإصدار (مثل /api/v1/payment_intents). الإصدار الحالي هو v1. وعند ظهور إصدارات أحدث سيعكسها المسار (مثل /api/v2/payment_intents).
• Node SDK: يقبل العميل baseUrl (الافتراضي https://api.orcarail.com/api/v1) وapiVersion (الافتراضي "v1"). لاستخدام إصدار API مختلف، اضبط baseUrl على المسار الأساسي ذي الإصدار المطلوب (مثل https://api.orcarail.com/api/v2). لا تتضمن معاملات إنشاء Payment Intent حقل إصدار؛ إذ يستخدم العميل الرابط الأساسي. راجع Node SDK للإعداد الكامل.
• PHP SDK: يقبل العميل base_url (الافتراضي https://api.orcarail.com/api/v1). وجّهه إلى مسار أساسي بإصدار آخر لتغيير إصدار API. راجع PHP SDK للإعداد الكامل.

المصادقة

تدعم نقطة النهاية هذه طريقتي المصادقة:

• رمز Bearer (JWT) — Authorization: Bearer YOUR_JWT_TOKEN
• مفتاح API (Basic Auth) — Authorization: Basic base64(key:secret)

الطلب

جسم الطلب

{
  "amount": "100.00",
  "currency": "usd",
  "payment_method_types": ["crypto"],
  "tokenId": 1,
  "networkId": 1,
  "return_url": "https://merchant.example.com/return",
  "cancel_url": "https://merchant.example.com/cancel",
  "description": "Payment for services",
  "metadata": {
    "order_id": "12345",
    "customer_id": "67890"
  },
  "expires_at": "2024-12-31T23:59:59Z",
  "withdrawal_addresses": { "evm": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" }
}

المعاملات

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

الاستجابة

استجابة النجاح

{
  "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",
  "cancelUrl": "https://merchant.example.com/cancel",
  "description": "Payment for services",
  "metadata": {
    "order_id": "12345",
    "customer_id": "67890"
  },
  "paymentLink": {
    "id": 1,
    "link": "https://pay.orcarail.com/pay/pl_abc123"
  },
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

حقول الاستجابة

الحقل	النوع	الوصف
id	string	المعرّف الفريد للـ Payment Intent (مثل 550e8400-e29b-41d4-a716-446655440000).
amount	string	المبلغ المطلوب تحصيله.
currency	string	رمز العملة.
status	string	الحالة الحالية للـ Payment Intent.
paymentMethodTypes	array	مصفوفة أنواع طرق الدفع.
clientSecret	string	مهم: يُعرض مرة واحدة فقط. استخدمه لتأكيد الـ Payment Intent.
returnUrl	string	رابط العودة الذي حددته.
cancelUrl	string	رابط الإلغاء الذي حددته (إن وُجد).
description	string	الوصف الذي قدمته (إن وُجد).
metadata	object	البيانات الوصفية التي قدمتها (إن وُجدت).
paymentLink	object	يحتوي رابط الدفع المستضاف في link.
expiresAt	string	موعد انتهاء صلاحية الـ Payment Intent (إن حُدد).
createdAt	string	وقت إنشاء الـ Payment Intent.
updatedAt	string	وقت آخر تحديث للـ Payment Intent.

مثال

cURL

curl https://api.orcarail.com/api/v1/payment_intents \
  -X POST \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "currency": "usd",
    "payment_method_types": ["crypto"],
    "tokenId": 1,
    "networkId": 1,
    "return_url": "https://merchant.example.com/return"
  }'

JavaScript (Node.js)

const response = await fetch(
  'https://api.orcarail.com/api/v1/payment_intents',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: '100.00',
      currency: 'usd',
      payment_method_types: ['crypto'],
      tokenId: 1,
      networkId: 1,
      return_url: 'https://merchant.example.com/return',
      description: 'Payment for services',
      metadata: {
        order_id: '12345',
      },
    }),
  }
)

const paymentIntent = await response.json()
console.log('Client Secret:', paymentIntent.clientSecret)
console.log('Payment Link:', paymentIntent.paymentLink.link)

Python

import requests

response = requests.post(
    'https://api.orcarail.com/api/v1/payment_intents',
    headers={
        'Authorization': f'Bearer {jwt_token}',
        'Content-Type': 'application/json',
    },
    json={
        'amount': '100.00',
        'currency': 'usd',
        'payment_method_types': ['crypto'],
        'tokenId': 1,
        'networkId': 1,
        'return_url': 'https://merchant.example.com/return',
        'description': 'Payment for services',
        'metadata': {
            'order_id': '12345',
        },
    },
)

payment_intent = response.json()
print(f"Client Secret: {payment_intent['clientSecret']}")
print(f"Payment Link: {payment_intent['paymentLink']['link']}")

PHP (SDK)

use OrcaRail\OrcaRailClient;

$orcarail = new OrcaRailClient([
    'api_key' => getenv('ORCARAIL_API_KEY'),
    'api_secret' => getenv('ORCARAIL_API_SECRET'),
]);

$intent = $orcarail->paymentIntents->create([
    'amount' => '100.00',
    'currency' => 'usd',
    'tokenId' => $tokenId,     // token UUID
    'networkId' => $networkId, // network UUID
    'return_url' => 'https://merchant.example.com/return',
    'description' => 'Payment for services',
    'metadata' => ['order_id' => '12345'],
]);

echo $intent->client_secret;
echo $intent->payment_link?->link;

القيمة الافتراضية لـ payment_method_types هي ['crypto']. مرّر price_id بدلًا من حقول المبلغ لتحصيل سعر من الكتالوج. راجع PHP SDK.

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

بعد إنشاء Payment Intent:

1. أكّد الـ Payment Intent — احصل على رابط التوجيه لعميلك
2. وجّه العميل إلى تطبيق الدفع المستضاف
3. عالِج العودة إلى رابط العودة