ویرایش Payment Intent

یک Payment Intent را ویرایش کنید تا جزئیاتش را پیش از تأیید و پرداخت تغییر دهید.

اندپوینت

PATCH /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).

بدنه درخواست

همه فیلدها اختیاری‌اند. فقط فیلدهایی را بفرستید که می‌خواهید تغییر کنند.

{
  "amount": "150.00",
  "currency": "usd",
  "description": "Updated payment description",
  "metadata": {
    "order_id": "12345",
    "updated_at": "2024-01-01T12:00:00Z"
  },
  "return_url": "https://merchant.example.com/new-return",
  "cancel_url": "https://merchant.example.com/new-cancel",
  "withdrawal_addresses": { "evm": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" }
}

پارامترها

پارامتر	نوع	الزامی	توضیح
amount	string	خیر	مبلغ دریافتی را تغییر می‌دهد. باید عددی مثبت باشد.
currency	string	خیر	کد ارز را تغییر می‌دهد.
description	string	خیر	توضیح را تغییر می‌دهد.
metadata	object	خیر	فراداده را تغییر می‌دهد. با فراداده موجود ادغام می‌شود.
return_url	string	خیر	آدرس بازگشت را تغییر می‌دهد.
cancel_url	string	خیر	آدرس لغو را تغییر می‌دهد.
withdrawal_addresses	object	خیر	آدرس‌های برداشت به تفکیک نوع زنجیره. برای استفاده از پیش‌فرض حساب، آن را نفرستید.

:::warning نکته فقط وقتی می‌توانید Payment Intent را ویرایش کنید که وضعیتش requires_payment_method یا requires_confirmation باشد. وقتی پرداخت در وضعیت processing یا succeeded باشد، دیگر قابل ویرایش نیست. :::

پاسخ

پاسخ موفق

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "150.00",
  "currency": "usd",
  "status": "requires_payment_method",
  "paymentMethodTypes": ["crypto"],
  "returnUrl": "https://merchant.example.com/new-return",
  "cancelUrl": "https://merchant.example.com/new-cancel",
  "description": "Updated payment description",
  "metadata": {
    "order_id": "12345",
    "updated_at": "2024-01-01T12:00:00Z"
  },
  "paymentLink": {
    "id": 1,
    "link": "https://pay.orcarail.com/pay/pl_abc123"
  },
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

نمونه

cURL

curl https://api.orcarail.com/api/v1/payment_intents/550e8400-e29b-41d4-a716-446655440000 \
  -X PATCH \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "150.00",
    "description": "Updated payment description"
  }'

JavaScript (Node.js)

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

const response = await fetch(
  `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}`,
  {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: '150.00',
      description: 'Updated payment description',
      metadata: {
        order_id: '12345',
        updated_at: new Date().toISOString(),
      },
    }),
  }
)

const updatedIntent = await response.json()
console.log('Updated Amount:', updatedIntent.amount)

Python

import requests

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

response = requests.patch(
    f'https://api.orcarail.com/api/v1/payment_intents/{payment_intent_id}',
    headers={
        'Authorization': f'Bearer {jwt_token}',
        'Content-Type': 'application/json',
    },
    json={
        'amount': '150.00',
        'description': 'Updated payment description',
        'metadata': {
            'order_id': '12345',
            'updated_at': '2024-01-01T12:00:00Z',
        },
    },
)

updated_intent = response.json()
print(f"Updated Amount: {updated_intent['amount']}")

PHP (SDK)

$updated = $orcarail->paymentIntents->update('550e8400-e29b-41d4-a716-446655440000', [
    'amount' => '150.00',
    'description' => 'Updated payment description',
    'metadata' => ['order_id' => '12345'],
]);

echo $updated->amount;

برای راه‌اندازی کلاینت SDK پی‌اچ‌پی را ببینید.

موارد استفاده

تغییر مبلغ پس از تغییر سبد خرید

اگر مشتری پیش از پرداخت سبد خریدش را تغییر دهد، مبلغ Payment Intent را به‌روز کنید:

async function updateCartTotal(paymentIntentId, newAmount) {
  const response = await fetch(
    `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}`,
    {
      method: 'PATCH',
      headers: {
        Authorization: `Bearer ${jwtToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        amount: newAmount.toFixed(2),
      }),
    }
  )

  return await response.json()
}

افزودن فراداده پس از ساخت سفارش

اطلاعات سفارش را به فراداده Payment Intent اضافه کنید:

async function addOrderMetadata(paymentIntentId, orderId) {
  const response = await fetch(
    `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}`,
    {
      method: 'PATCH',
      headers: {
        Authorization: `Bearer ${jwtToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        metadata: {
          order_id: orderId,
          created_at: new Date().toISOString(),
        },
      }),
    }
  )

  return await response.json()
}

مدیریت خطا

اگر بخواهید Payment Intentی را که پرداخت شده یا در حال پردازش است ویرایش کنید، خطا دریافت می‌کنید:

{
  "statusCode": 400,
  "message": "Cannot update Payment Intent with status 'succeeded'",
  "error": "Bad Request"
}

همیشه پیش از تلاش برای ویرایش، وضعیت Payment Intent را بررسی کنید:

async function safeUpdatePaymentIntent(paymentIntentId, updates) {
  // First, retrieve the current Payment Intent
  const getResponse = await fetch(
    `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}`,
    {
      headers: {
        Authorization: `Bearer ${jwtToken}`,
      },
    }
  )

  const currentIntent = await getResponse.json()

  // Check if update is allowed
  const allowedStatuses = ['requires_payment_method', 'requires_confirmation']
  if (!allowedStatuses.includes(currentIntent.status)) {
    throw new Error(
      `Cannot update Payment Intent with status '${currentIntent.status}'`
    )
  }

  // Proceed with update
  const updateResponse = await fetch(
    `https://api.orcarail.com/api/v1/payment_intents/${paymentIntentId}`,
    {
      method: 'PATCH',
      headers: {
        Authorization: `Bearer ${jwtToken}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(updates),
    }
  )

  return await updateResponse.json()
}

قدم‌های بعدی

• تأیید Payment Intent — پس از ویرایش، آن را تأیید کنید تا آدرس انتقال را بگیرید
• دریافت Payment Intent — جزئیات به‌روزشده را بررسی کنید