تأیید 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);

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 — وضعیت پرداخت را بررسی کنید
• راه‌اندازی وب‌هوک‌ها — اعلان‌های لحظه‌ای پرداخت دریافت کنید