استرجاع Payment Intent

استرجع تفاصيل Payment Intent للتحقق من حالته والحصول على معلومات محدّثة.

نقطة النهاية

GET /api/v1/payment_intents/:id

المصادقة

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

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

الطلب

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

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

الاستجابة

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

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

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

الحقل	النوع	الوصف
id	string	المعرّف الفريد للـ Payment Intent.
amount	string	المبلغ المحصَّل.
currency	string	رمز العملة.
status	string	الحالة الحالية للـ Payment Intent. راجع قيم الحالة أدناه.
paymentMethodTypes	array	مصفوفة أنواع طرق الدفع المستخدمة.
returnUrl	string	رابط العودة المحدد.
cancelUrl	string	رابط الإلغاء (إن حُدد).
description	string	الوصف (إن قُدّم).
metadata	object	البيانات الوصفية (إن قُدّمت).
paymentLink	object	كائن رابط الدفع مع رابط صفحة الدفع.
latestTransaction	object	أحدث معاملة مرتبطة بهذا الـ Payment Intent.
latestTransaction.id	string	معرّف المعاملة.
latestTransaction.status	string	حالة المعاملة.
latestTransaction.amount	string	مبلغ المعاملة.
latestTransaction.currency	string	عملة المعاملة.
latestTransaction.hash	string	تجزئة المعاملة على البلوكتشين (إن اكتملت).
expiresAt	string | null	موعد انتهاء صلاحية الـ Payment Intent (إن حُدد).
createdAt	string	وقت إنشاء الـ Payment Intent.
updatedAt	string	وقت آخر تحديث للـ Payment Intent.

قيم الحالة

الحالة	الوصف
requires_payment_method	أُنشئ الـ PaymentIntent لكن لم تُرفق به طريقة دفع بعد.
requires_confirmation	للـ PaymentIntent طريقة دفع مرفقة لكنه يحتاج إلى تأكيد.
processing	الـ PaymentIntent قيد المعالجة على البلوكتشين.
succeeded	نجح الـ PaymentIntent وعولجت الدفعة.
canceled	أُلغي الـ PaymentIntent.

مثال

cURL

curl https://api.orcarail.com/api/v1/payment_intents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

JavaScript (Node.js)

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

const response = await fetch(
  `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}`,
  {
    headers: {
      Authorization: `Bearer ${jwtToken}`,
    },
  }
)

const paymentIntent = await response.json()

console.log('Status:', paymentIntent.status)
console.log('Amount:', paymentIntent.amount)

if (paymentIntent.status === 'succeeded') {
  console.log('Transaction Hash:', paymentIntent.latestTransaction?.hash)
}

Python

import requests

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

response = requests.get(
    f'https://api.orcarail.com/api/v1/payment_intents/{payment_intent_id}',
    headers={
        'Authorization': f'Bearer {jwt_token}',
    },
)

payment_intent = response.json()

print(f"Status: {payment_intent['status']}")
print(f"Amount: {payment_intent['amount']}")

if payment_intent['status'] == 'succeeded':
    print(f"Transaction Hash: {payment_intent['latestTransaction']['hash']}")

PHP (SDK)

$intent = $orcarail->paymentIntents->retrieve('550e8400-e29b-41d4-a716-446655440000');

echo $intent->status;
echo $intent->amount;
echo $intent->latest_transaction?->hash;

راجع PHP SDK لإعداد العميل.

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

التحقق من حالة الدفع بعد التوجيه

بعد عودة العميل إلى return_url الخاص بك، استرجع الـ Payment Intent للتحقق من نجاح الدفع:

// Extract from URL query params
const urlParams = new URLSearchParams(window.location.search)
const paymentIntentId = urlParams.get('payment_intent')

if (paymentIntentId) {
  const response = await fetch(
    `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}`,
    {
      headers: {
        Authorization: `Bearer ${jwtToken}`,
      },
    }
  )

  const paymentIntent = await response.json()

  switch (paymentIntent.status) {
    case 'succeeded':
      // Payment completed successfully
      showSuccessMessage()
      fulfillOrder(paymentIntent.metadata.order_id)
      break
    case 'processing':
      // Payment is being processed
      showProcessingMessage()
      break
    case 'canceled':
      // Payment was canceled
      showCanceledMessage()
      break
    default:
      // Handle other statuses
      showErrorMessage()
  }
}

الاستطلاع الدوري لتحديثات الحالة

إن لم تكن تستخدم الـ webhooks، يمكنك استطلاع نقطة نهاية الـ Payment Intent دوريًا للتحقق من تحديثات الحالة:

async function pollPaymentStatus(paymentIntentId, maxAttempts = 30) {
  for (let i = 0; i < maxAttempts; i++) {
    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') {
      return { success: true, paymentIntent }
    }

    if (paymentIntent.status === 'canceled') {
      return { success: false, paymentIntent }
    }

    // Wait 2 seconds before next poll
    await new Promise((resolve) => setTimeout(resolve, 2000))
  }

  return { success: false, error: 'Timeout' }
}

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

• تحديث Payment Intent — عدّل تفاصيل الدفع قبل التأكيد
• إعداد الـ webhooks — استقبل تحديثات الحالة لحظيًا بدلًا من الاستطلاع