تأكيد Payment Intent

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

نقطة النهاية

POST /api/v1/payment_intents/:id/confirm

المصادقة

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

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

الطلب

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

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

جسم الطلب

{
  "client_secret": "550e8400-e29b-41d4-a716-446655440000_secret_abc123",
  "return_url": "https://merchant.example.com/return",
  "payment_method_data": {
    "type": "crypto"
  }
}

المعاملات

المعامل	النوع	مطلوب	الوصف
client_secret	string	نعم	الـ client secret من استجابة إنشاء الـ Payment Intent.
return_url	string	لا	يستبدل رابط العودة المحدد عند إنشاء الـ Payment Intent.
payment_method_data	object	لا	بيانات طريقة الدفع. حاليًا لا يُدعم إلا type: "crypto".

الاستجابة

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

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

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

الحقل	النوع	الوصف
id	string	معرّف الـ Payment Intent.
status	string	الحالة المحدّثة (عادةً requires_confirmation).
nextAction	object	يحتوي رابط التوجيه في redirectToUrl.url.
nextAction.type	string	دائمًا "redirect_to_url" لمدفوعات الكريبتو.
nextAction.redirectToUrl.url	string	الرابط الذي توجّه إليه عميلك. وهو صفحة الدفع المستضافة.

مثال

cURL

curl https://api.orcarail.com/api/v1/payment_intents/550e8400-e29b-41d4-a716-446655440000/confirm \
  -X POST \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_secret": "550e8400-e29b-41d4-a716-446655440000_secret_abc123"
  }'

JavaScript (Node.js)

const paymentIntentId = '550e8400-e29b-41d4-a716-446655440000'
const clientSecret = '550e8400-e29b-41d4-a716-446655440000_secret_abc123'

const response = await fetch(
  `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}/confirm`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      client_secret: clientSecret,
    }),
  }
)

const confirmedIntent = await response.json()
const redirectUrl = confirmedIntent.nextAction.redirectToUrl.url

// Redirect your customer to this URL
window.location.href = redirectUrl

Python

import requests

payment_intent_id = '550e8400-e29b-41d4-a716-446655440000'
client_secret = '550e8400-e29b-41d4-a716-446655440000_secret_abc123'

response = requests.post(
    f'https://api.orcarail.com/api/v1/payment_intents/{payment_intent_id}/confirm',
    headers={
        'Authorization': f'Bearer {jwt_token}',
        'Content-Type': 'application/json',
    },
    json={
        'client_secret': client_secret,
    },
)

confirmed_intent = response.json()
redirect_url = confirmed_intent['nextAction']['redirectToUrl']['url']

# Redirect your customer to this URL
print(f"Redirect customer to: {redirect_url}")

PHP (SDK)

$confirmed = $orcarail->paymentIntents->confirm($intentId, [
    'client_secret' => $clientSecret,
    'return_url' => 'https://merchant.example.com/return',
]);

$payUrl = $confirmed->pay_url ?? $confirmed->next_action?->redirect_to_url?->url;
header('Location: ' . $payUrl);

ترسل PHP SDK مفتاح API الخاص بك مع الـ client secret، لذا يعمل التأكيد من الخادم دون JWT للمستخدم.

تدفق الدفع المستضاف

بعد تأكيد الـ Payment Intent، وجّه عميلك إلى الرابط في nextAction.redirectToUrl.url. ستقوم صفحة الدفع المستضافة بما يلي:

1. عرض مبلغ الدفع وتفاصيله
2. السماح للعميل بربط محفظة الكريبتو الخاصة به
3. معالجة الدفع على السلسلة
4. إعادة التوجيه إلى return_url الخاص بك مع معاملات الاستعلام

معالجة رابط العودة

بعد اكتمال الدفع (أو إلغائه)، يُوجَّه العملاء إلى return_url الخاص بك مع معاملات الاستعلام:

https://merchant.example.com/return?payment_intent=550e8400-e29b-41d4-a716-446655440000&payment_intent_client_secret=550e8400-e29b-41d4-a716-446655440000_secret_abc123

يجب عليك:

1. استخراج payment_intent وpayment_intent_client_secret من سلسلة الاستعلام
2. استرجاع الـ Payment Intent للتحقق من حالته
3. معالجة الدفعة وفقًا لذلك (مثل عرض صفحة نجاح أو تحديث حالة الطلب)

مثال على معالج رابط العودة

// Handle return URL callback
const urlParams = new URLSearchParams(window.location.search)
const paymentIntentId = urlParams.get('payment_intent')
const clientSecret = urlParams.get('payment_intent_client_secret')

if (paymentIntentId && clientSecret) {
  // Retrieve the Payment Intent to check status
  const response = await fetch(
    `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}`,
    {
      headers: {
        Authorization: `Bearer ${jwtToken}`,
      },
    }
  )

  const paymentIntent = await response.json()

  if (paymentIntent.status === 'succeeded') {
    // Payment successful!
    showSuccessPage()
  } else if (paymentIntent.status === 'canceled') {
    // Payment was canceled
    showCanceledPage()
  } else {
    // Payment is still processing
    showProcessingPage()
  }
}

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

• استرجاع Payment Intent — تحقق من حالة الدفع
• إعداد الـ webhooks — استقبل إشعارات الدفع لحظيًا