دریافت 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;

برای راه‌اندازی کلاینت 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()
  }
}

پرس‌وجوی دوره‌ای وضعیت

اگر از وب‌هوک استفاده نمی‌کنید، می‌توانید به‌طور دوره‌ای اندپوینت 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 — جزئیات پرداخت را پیش از تأیید تغییر دهید
• راه‌اندازی وب‌هوک‌ها — به‌جای پرس‌وجوی دوره‌ای، به‌روزرسانی‌های لحظه‌ای وضعیت بگیرید