ساخت Payment Intent

برای شروع دریافت وجه از مشتری یک Payment Intent بسازید.

اندپوینت

POST /api/v1/payment_intents

نسخه API در مسیر URL قرار دارد (v1). در بدنه درخواست فیلد نسخه وجود ندارد.

نسخه API و SDK

نسخه در URL: مسیر پایه شامل نسخه است (مثلاً /api/v1/payment_intents). نسخه فعلی v1 است. وقتی نسخه‌های جدیدتر بیایند، مسیر آن را نشان می‌دهد (مثلاً /api/v2/payment_intents).
SDK نود: کلاینت baseUrl (پیش‌فرض https://api.orcarail.com/api/v1) و apiVersion (پیش‌فرض "v1") را می‌پذیرد. برای استفاده از نسخه دیگر API، baseUrl را روی پایه نسخه‌دار مورد نظر تنظیم کنید (مثلاً https://api.orcarail.com/api/v2). پارامترهای ساخت Payment Intent فیلد نسخه ندارند؛ کلاینت از URL پایه استفاده می‌کند. برای پیکربندی کامل SDK نود را ببینید.
SDK پی‌اچ‌پی: کلاینت base_url (پیش‌فرض https://api.orcarail.com/api/v1) را می‌پذیرد. برای تغییر نسخه API آن را به پایه نسخه‌دار دیگری اشاره دهید. برای پیکربندی کامل SDK پی‌اچ‌پی را ببینید.

احراز هویت

این اندپوینت از هر دو روش احراز هویت پشتیبانی می‌کند:

توکن Bearer (JWT) — Authorization: Bearer YOUR_JWT_TOKEN
کلید API (Basic Auth) — Authorization: Basic base64(key:secret)

درخواست

بدنه درخواست

{
  "amount": "100.00",
  "currency": "usd",
  "payment_method_types": ["crypto"],
  "tokenId": 1,
  "networkId": 1,
  "return_url": "https://merchant.example.com/return",
  "cancel_url": "https://merchant.example.com/cancel",
  "description": "Payment for services",
  "metadata": {
    "order_id": "12345",
    "customer_id": "67890"
  },
  "expires_at": "2024-12-31T23:59:59Z",
  "withdrawal_addresses": { "evm": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" }
}

پارامترها

پارامتر	نوع	الزامی	توضیح
`amount`	string	بله	مبلغ دریافتی، در کوچک‌ترین واحد ارز (مثلاً سنت برای USD). باید عددی مثبت باشد.
`currency`	string	بله	کد سه‌حرفی ISO ارز (مثلاً `usd`، `eur`).
`payment_method_types`	array	بله	آرایه انواع روش پرداخت. باید شامل `"crypto"` باشد.
`tokenId`	number	بله	شناسه توکنی که پذیرفته می‌شود (مثلاً USDC، USDT).
`networkId`	number	بله	شناسه شبکه بلاکچین (مثلاً Ethereum، Polygon).
`return_url`	string	بله	آدرسی که مشتری پس از تکمیل پرداخت به آن منتقل می‌شود.
`cancel_url`	string	خیر	آدرسی که اگر مشتری پرداخت را لغو کند به آن منتقل می‌شود.
`description`	string	خیر	توضیح اختیاری پرداخت.
`metadata`	object	خیر	مجموعه‌ای از جفت‌های کلید-مقدار که می‌توانید به Payment Intent پیوست کنید.
`expires_at`	string	خیر	زمان انقضای Payment Intent به قالب ISO 8601.
`withdrawal_addresses`	object	خیر	آدرس‌های برداشت به تفکیک نوع زنجیره. کلیدها باید نوع زنجیره معتبر باشند: `evm`، `solana`، `bitcoin`، `tron`، `cosmos`، `polkadot`، `move`، `ton` (مثلاً `{ "evm": "0x...", "solana": "..." }`). اگر برای یک زنجیره حذف یا خالی باشد، مقدار پیش‌فرض حساب شما از تنظیمات برداشت استفاده می‌شود.

پاسخ

پاسخ موفق

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "100.00",
  "currency": "usd",
  "status": "requires_payment_method",
  "paymentMethodTypes": ["crypto"],
  "clientSecret": "550e8400-e29b-41d4-a716-446655440000_secret_abc123",
  "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"
  },
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

فیلدهای پاسخ

فیلد	نوع	توضیح
`id`	string	شناسه یکتای Payment Intent (مثلاً `550e8400-e29b-41d4-a716-446655440000`).
`amount`	string	مبلغ دریافتی.
`currency`	string	کد ارز.
`status`	string	وضعیت فعلی Payment Intent.
`paymentMethodTypes`	array	آرایه انواع روش پرداخت.
`clientSecret`	string	مهم: فقط یک بار نمایش داده می‌شود. برای تأیید Payment Intent از آن استفاده کنید.
`returnUrl`	string	آدرس بازگشتی که تعیین کرده‌اید.
`cancelUrl`	string	آدرس لغوی که تعیین کرده‌اید (در صورت وجود).
`description`	string	توضیحی که داده‌اید (در صورت وجود).
`metadata`	object	فراداده‌ای که داده‌اید (در صورت وجود).
`paymentLink`	object	آدرس صفحه پرداخت میزبانی‌شده را در `link` دارد.
`expiresAt`	string	زمان انقضای Payment Intent (در صورت تعیین).
`createdAt`	string	زمان ساخت Payment Intent.
`updatedAt`	string	زمان آخرین به‌روزرسانی Payment Intent.

نمونه

cURL

curl https://api.orcarail.com/api/v1/payment_intents \
  -X POST \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "currency": "usd",
    "payment_method_types": ["crypto"],
    "tokenId": 1,
    "networkId": 1,
    "return_url": "https://merchant.example.com/return"
  }'

JavaScript (Node.js)

const response = await fetch(
  'https://api.orcarail.com/api/v1/payment_intents',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: '100.00',
      currency: 'usd',
      payment_method_types: ['crypto'],
      tokenId: 1,
      networkId: 1,
      return_url: 'https://merchant.example.com/return',
      description: 'Payment for services',
      metadata: {
        order_id: '12345',
      },
    }),
  }
)

const paymentIntent = await response.json()
console.log('Client Secret:', paymentIntent.clientSecret)
console.log('Payment Link:', paymentIntent.paymentLink.link)

Python

import requests

response = requests.post(
    'https://api.orcarail.com/api/v1/payment_intents',
    headers={
        'Authorization': f'Bearer {jwt_token}',
        'Content-Type': 'application/json',
    },
    json={
        'amount': '100.00',
        'currency': 'usd',
        'payment_method_types': ['crypto'],
        'tokenId': 1,
        'networkId': 1,
        'return_url': 'https://merchant.example.com/return',
        'description': 'Payment for services',
        'metadata': {
            'order_id': '12345',
        },
    },
)

payment_intent = response.json()
print(f"Client Secret: {payment_intent['clientSecret']}")
print(f"Payment Link: {payment_intent['paymentLink']['link']}")

PHP (SDK)

use OrcaRail\OrcaRailClient;

$orcarail = new OrcaRailClient([
    'api_key' => getenv('ORCARAIL_API_KEY'),
    'api_secret' => getenv('ORCARAIL_API_SECRET'),
]);

$intent = $orcarail->paymentIntents->create([
    'amount' => '100.00',
    'currency' => 'usd',
    'tokenId' => $tokenId,     // token UUID
    'networkId' => $networkId, // network UUID
    'return_url' => 'https://merchant.example.com/return',
    'description' => 'Payment for services',
    'metadata' => ['order_id' => '12345'],
]);

echo $intent->client_secret;
echo $intent->payment_link?->link;

مقدار پیش‌فرض payment_method_types برابر ['crypto'] است. برای دریافت قیمت کاتالوگ، به‌جای فیلدهای مبلغ price_id بفرستید. SDK پی‌اچ‌پی را ببینید.

قدم‌های بعدی

پس از ساخت Payment Intent:

Payment Intent را تأیید کنید — آدرس انتقال را برای مشتری بگیرید
مشتری را به اپ پرداخت میزبانی‌شده منتقل کنید
بازگشت به آدرس بازگشت را مدیریت کنید

اندپوینت​

نسخه API و SDK​

احراز هویت​

درخواست​

بدنه درخواست​

پارامترها​

پاسخ​

پاسخ موفق​

فیلدهای پاسخ​

نمونه​

cURL​

JavaScript (Node.js)​

Python​

PHP (SDK)​

قدم‌های بعدی​