مرجع API مربوط به Payment Intentها

مرجع کامل اندپوینت‌های API مربوط به Payment Intentها.

آدرس پایه

https://api.orcarail.com/api/v1

نسخه API در مسیر است (v1). برای استفاده از نسخه دیگر، از آدرس پایه متناظر استفاده کنید (مثلاً https://api.orcarail.com/api/v2). SDK نود از baseUrl و apiVersion در پیکربندی استفاده می‌کند؛ SDK نود را ببینید.

ساخت Payment Intent

یک Payment Intent جدید بسازید.

POST /payment_intents

احراز هویت

توکن Bearer (JWT) یا کلید API (Basic Auth)

بدنه درخواست

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

پاسخ

{
  "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",
  "paymentLink": {
    "id": 1,
    "link": "https://pay.orcarail.com/pay/pl_abc123"
  },
  "createdAt": "2024-01-01T00:00:00.000Z"
}

دریافت Payment Intent

جزئیات یک Payment Intent را بگیرید.

GET /payment_intents/:id

احراز هویت

توکن Bearer (JWT) یا کلید API (Basic Auth)

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
`id`	string	بله	شناسه Payment Intent (مثلاً `550e8400-e29b-41d4-a716-446655440000`)

پاسخ

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

تأیید Payment Intent

یک Payment Intent را تأیید کنید تا آدرس انتقال را بگیرید.

POST /payment_intents/:id/confirm

احراز هویت

توکن Bearer (JWT) یا کلید API (Basic Auth)

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
`id`	string	بله	شناسه Payment Intent

بدنه درخواست

پارامتر	نوع	الزامی	توضیح
`client_secret`	string	بله	client secret از Payment Intent
`return_url`	string	خیر	جایگزینی آدرس بازگشت
`payment_method_data`	object	خیر	داده روش پرداخت

پاسخ

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "requires_confirmation",
  "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"
    }
  }
}

لغو Payment Intent

یک Payment Intent را لغو کنید. پس از لغو، دیگر برای پرداخت قابل استفاده نیست.

POST /payment_intents/:id/cancel

احراز هویت

کلید API (Basic Auth) — الزامی

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
`id`	string	بله	شناسه Payment Intent

پاسخ

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "canceled",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

تکمیل Payment Intent

یک Payment Intent را در حال پردازش علامت بزنید و وب‌هوک payment_intent.processing را فعال کنید. این را پس از بازگشت مشتری به آدرس بازگشت (مثلاً از صفحه موفقیت) فراخوانی کنید تا بک‌اند شما intent را در حال پردازش علامت بزند، در حالی که پرس‌وجو می‌کنید یا منتظر وب‌هوک نهایی payment_intent.complete هستید.

POST /payment_intents/:id/complete

احراز هویت

کلید API (Basic Auth) — الزامی

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
`id`	string	بله	شناسه Payment Intent

پاسخ

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

شبیه‌سازی پرداخت (فقط sandbox)

یک Payment Intent را بدون انتقال روی زنجیره، فقط در یک سازمان sandbox تکمیل کنید. پرداخت از جریان عادی عبور می‌کند و همان وب‌هوک‌های معمول را با livemode: false ارسال می‌کند و تراکنش آن simulated: true دارد. پرداخت‌های شبیه‌سازی‌شده هرگز قابل برداشت نیستند.

POST /payment_intents/:id/simulate

احراز هویت

کلید API (Basic Auth) یک سازمان sandbox (ak_test_…) — الزامی

خطاها

وضعیت	کد	چه زمانی
403	`SIMULATION_SANDBOX_ONLY`	intent متعلق به یک سازمان live است

صفحه پرداخت میزبانی‌شده از معادل عمومی POST /payments/links/:slug/simulate استفاده می‌کند (فقط لینک‌های sandbox).

ویرایش Payment Intent

یک Payment Intent را پیش از تأیید ویرایش کنید.

PATCH /payment_intents/:id

احراز هویت

توکن Bearer (JWT) یا کلید API (Basic Auth)

پارامترهای مسیر

پارامتر	نوع	الزامی	توضیح
`id`	string	بله	شناسه Payment Intent

بدنه درخواست

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

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

پاسخ

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "150.00",
  "currency": "usd",
  "status": "requires_payment_method",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

کدهای وضعیت

کد وضعیت	توضیح
`200`	موفق
`201`	ساخته شد
`400`	درخواست نامعتبر
`401`	احراز هویت نشده
`404`	یافت نشد
`500`	خطای داخلی سرور

قالب پاسخ خطا

{
  "statusCode": 400,
  "message": "Invalid request",
  "error": "Bad Request"
}

محدودیت نرخ

درخواست‌های API محدودیت نرخ دارند. محدودیت‌های فعلی:

درخواست‌های احراز هویت‌شده: ۱۰۰ درخواست در دقیقه برای هر کلید API/کاربر
درخواست‌های بدون احراز هویت: ۱۰ درخواست در دقیقه برای هر IP

هدرهای محدودیت نرخ در پاسخ‌ها آمده‌اند:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

همچنین ببینید

راهنمای Payment Intentها — راهنماهای کامل
وب‌هوک‌ها — دریافت اعلان‌های پرداخت

آدرس پایه​

ساخت Payment Intent​

احراز هویت​

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

پاسخ​

دریافت Payment Intent​

احراز هویت​

پارامترهای مسیر​

پاسخ​

تأیید Payment Intent​

احراز هویت​

پارامترهای مسیر​

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

پاسخ​

لغو Payment Intent​

احراز هویت​

پارامترهای مسیر​

پاسخ​

تکمیل Payment Intent​

احراز هویت​

پارامترهای مسیر​

پاسخ​

شبیه‌سازی پرداخت (فقط sandbox)​

احراز هویت​

خطاها​

ویرایش Payment Intent​

احراز هویت​

پارامترهای مسیر​

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

پاسخ​

کدهای وضعیت​

قالب پاسخ خطا​

محدودیت نرخ​

همچنین ببینید​

آدرس پایه

ساخت Payment Intent

احراز هویت

بدنه درخواست

پاسخ

دریافت Payment Intent

احراز هویت

پارامترهای مسیر

پاسخ

تأیید Payment Intent

احراز هویت

پارامترهای مسیر

بدنه درخواست

پاسخ

لغو Payment Intent

احراز هویت

پارامترهای مسیر

پاسخ

تکمیل Payment Intent

احراز هویت

پارامترهای مسیر

پاسخ

شبیه‌سازی پرداخت (فقط sandbox)

احراز هویت

خطاها

ویرایش Payment Intent

احراز هویت

پارامترهای مسیر

بدنه درخواست

پاسخ

کدهای وضعیت

قالب پاسخ خطا

محدودیت نرخ

همچنین ببینید