شروع کار

با API ‏OrcaRail در چند قدم پرداخت با ارز دیجیتال (استیبل کوین‌هایی مثل تتر و USDC) را در سایت یا اپلیکیشن خود فعال کنید.

داشبورد و اپلیکیشن

در داشبورد OrcaRail می‌توانید ثبت‌نام و ورود کنید، راه‌اندازی مرحله‌به‌مرحله سازمان را انجام دهید، کلید API بسازید و کاربران را مدیریت کنید.

سازمان (organization) فضای کاری حساب OrcaRail شماست. پرداخت‌ها، کلیدهای API، اعضای تیم و تنظیمات صورت‌حساب همگی داخل یک سازمان قرار دارند.

• آدرس داشبورد: https://app.orcarail.com (در نصب روی سرور خودتان، از آدرس اپلیکیشن خودتان استفاده کنید.)

کاربرد	مسیر
ورود	/sign-in
ثبت‌نام	/sign-up
راه‌اندازی مرحله‌ای	اگر سازمان هنوز راه‌اندازی نشده باشد، پس از ورود به اینجا هدایت می‌شوید
کلیدهای API	/api-keys
کاربران	/users
فراموشی رمز عبور	/forgot-password
تنظیمات	/settings
داشبورد اصلی	/

نمای کلی

OrcaRail یک API و SDK استاندارد و ساده برای دریافت پرداخت با ارز دیجیتال (رمز ارز) ارائه می‌دهد. با OrcaRail می‌توانید:

• از مشتریان خود پرداخت با استیبل کوین بگیرید
• Payment Intent بسازید و کاربر را به صفحه پرداخت آماده هدایت کنید
• برای رویدادهای پرداخت اعلان وب‌هوک دریافت کنید
• کلیدهای API و احراز هویت را مدیریت کنید

ساخت حساب

برای شروع کار با OrcaRail باید یک حساب بسازید.

از طریق داشبورد

1. ثبت‌نام — داشبورد ← ثبت‌نام را باز کنید، ایمیل، رمز عبور و نام خود را وارد کنید و فرم را ارسال کنید.
2. تأیید ایمیل — صندوق ایمیل خود را بررسی کنید و روی لینک تأیید بزنید (یا از endpoint تأیید در API، که پایین‌تر آمده، استفاده کنید).
3. ورود — داشبورد ← ورود را باز کنید و اطلاعات ورود را وارد کنید؛ به داشبورد هدایت می‌شوید.
4. ساخت اولین سازمان — پس از ورود، OrcaRail برای ادامه کار در داشبورد به یک سازمان نیاز دارد. اگر حساب شما هنوز سازمانی ندارد، به راه‌اندازی مرحله‌ای هدایت می‌شوید. نام سازمان را وارد کنید، slug ساخته‌شده را تأیید یا ویرایش کنید و سازمان را بسازید؛ شما مالک آن می‌شوید.
5. تکمیل راه‌اندازی مرحله‌ای — حالت فروش را انتخاب کنید، محصولات و قیمت‌ها را بسازید یا ویرایش کنید، اولین کلید API را بسازید و یک ویجت ایجاد کنید. تا این مراحل لازم برای آن سازمان کامل نشود، داشبورد قفل می‌ماند.
6. کپی اطلاعات API — هنگام راه‌اندازی، key و secret را فوراً کپی کنید. secret فقط یک بار نمایش داده می‌شود و بعداً قابل بازیابی نیست.
7. تیم و کاربران (اختیاری) — برای دعوت اعضای تیم از داشبورد ← کاربران استفاده کنید (دعوت با ایمیل و مدیریت نقش‌ها). اعضای تیم به سازمان شما دعوت می‌شوند.

روش جایگزین: از طریق API

endpoint ثبت‌نام

POST /api/v1/auth/email/register

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

{
  "email": "[email protected]",
  "password": "secure-password",
  "firstName": "John",
  "lastName": "Doe"
}

پاسخ: 204 No Content

پس از ثبت‌نام یک ایمیل تأیید دریافت می‌کنید. برای فعال شدن حساب روی لینک داخل ایمیل بزنید.

تأیید ایمیل

POST /api/v1/auth/email/confirm

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

{
  "hash": "confirmation-token-from-email"
}

:::tip از سندباکس شروع کنید در داشبورد روی Go to sandbox بزنید تا یک نسخه فقط-تست‌نت از سازمان خود با کلیدهای ak_test_، USDC تستی رایگان و پرداخت شبیه‌سازی‌شده بگیرید. سازمان‌های سندباکس را ببینید. :::

ساخت کلید API

پس از تأیید حساب و ساخت اولین سازمان، می‌توانید برای احراز هویت درخواست‌ها کلید API بسازید. ساده‌ترین راه داشبورد است: به داشبورد ← API Keys بروید، روی Create API key بزنید، یک نام (و در صورت نیاز آدرس وب‌هوک) وارد کنید و key و secret را فوراً کپی کنید.

روش جایگزین با API — ساخت کلید API

POST /api/v1/organizations/:organizationId/api-keys
Authorization: Bearer YOUR_JWT_TOKEN

این درخواست برای سازمانی که با :organizationId مشخص شده یک کلید API می‌سازد. Bearer token باید به آن سازمان دسترسی داشته باشد.

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

{
  "name": "Production API Key"
}

پاسخ:

{
  "apiKey": {
    "id": 1,
    "name": "Production API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  },
  "key": "ak_live_abc123def456",
  "secret": "sk_live_xyz789uvw012"
}

:::warning مهم secret را فوراً ذخیره کنید! فقط یک بار نمایش داده می‌شود و بعداً قابل بازیابی نیست. اگر آن را گم کنید، باید کلید API جدیدی بسازید. :::

روش جایگزین با API — فهرست کلیدهای API

GET /api/v1/organizations/:organizationId/api-keys
Authorization: Bearer YOUR_JWT_TOKEN

پاسخ:

[
  {
    "id": 1,
    "name": "Production API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

روش جایگزین با API — باطل کردن کلید API

POST /api/v1/api-keys/:id/revoke
Authorization: Bearer YOUR_JWT_TOKEN

احراز هویت

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

1. Bearer Token (JWT) - برای درخواست‌هایی که کاربر در آن‌ها وارد شده است
2. کلید API (Basic Auth) - برای درخواست‌های سرور به سرور

استفاده از Bearer Token

ابتدا وارد شوید تا JWT token بگیرید:

POST /api/v1/auth/email/login

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

{
  "email": "[email protected]",
  "password": "secure-password"
}

پاسخ:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "refresh_token_here",
  "tokenExpires": 3600,
  "user": {
    "id": 1,
    "email": "[email protected]"
  }
}

سپس token را در درخواست‌های بعدی بفرستید:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

استفاده از کلید API

برای درخواست‌های سرور به سرور، از Basic Authentication با کلید API خود استفاده کنید:

Authorization: Basic base64(key:secret)

نمونه با curl:

curl https://api.orcarail.com/api/v1/payment_intents \
  -u ak_live_abc123def456:sk_live_xyz789uvw012

استفاده از SDK نود جی‌اس

ساده‌ترین راه اتصال درگاه پرداخت، SDK رسمی Node.js است. آن را از npm نصب کنید:

npm install @orcarail/node

• پکیج npm: @orcarail/node

سپس یک client بسازید و از Payment Intent، Pay و Webhook استفاده کنید:

const OrcaRail = require('@orcarail/node').default
const orcarail = new OrcaRail(
  process.env.ORCARAIL_API_KEY,
  process.env.ORCARAIL_API_SECRET
)

const intent = await orcarail.paymentIntents.create({
  amount: '100.00',
  currency: 'usd',
  payment_method_types: ['crypto'],
  tokenId: 1,
  networkId: 1,
  return_url: 'https://yourapp.com/success',
})

برای نصب کامل، تنظیمات، Payment Intent و بررسی امضای وب‌هوک، راهنمای SDK نود جی‌اس را ببینید.

استفاده از SDK پی‌اچ‌پی

برای اپلیکیشن‌های PHP 8.1 به بالا، SDK رسمی را با Composer نصب کنید:

composer require orcarail/orcarail-php

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://yourapp.com/success',
]);

برای تنظیمات، اشتراک‌ها، ابزارهای کاتالوگ و بررسی امضای وب‌هوک، راهنمای SDK پی‌اچ‌پی را ببینید.

امتحان اپلیکیشن نمونه

یک اپلیکیشن نمونه متن‌باز کل روند را نشان می‌دهد: ساخت intent، هدایت به صفحه پرداخت، صفحه موفقیت و وب‌هوک‌ها.

• مخزن: https://github.com/OrcaRail/demo
• مستندات: راهنمای اپلیکیشن نمونه

مخزن را clone کنید، کلید و secret API را تنظیم کنید و آن را محلی اجرا کنید یا روی Vercel منتشر کنید.

قدم‌های بعدی

حالا که حساب و کلید API دارید، می‌توانید:

• SDK نود جی‌اس - پیاده‌سازی با @orcarail/node
• SDK پی‌اچ‌پی - پیاده‌سازی با orcarail/orcarail-php
• اپلیکیشن نمونه - اجرای نسخه نمایشی متن‌باز
• ساخت Payment Intent - شروع دریافت پرداخت
• راه‌اندازی وب‌هوک - دریافت اعلان‌های پرداخت
• مرجع API - مشاهده همه endpointها