نمای کلی اشتراک‌ها

اشتراک‌های OrcaRail به شما امکان می‌دهند پرداخت‌های دوره‌ای کریپتو از پرداخت‌کنندگان دریافت کنید. REST API از یک منبع اشتراک متعارف با فیلدهای snake_case استفاده می‌کند. OrcaRail قابلیت auto_charge را اضافه می‌کند که در آن کیف پول داغ OrcaRail مبلغ هر دوره را از کیف پول پرداخت‌کننده روی EVM (allowance در ERC-20 و transferFrom) یا سولانا (delegation توکن SPL) برداشت می‌کند. برداشت خودکار روی بیت‌کوین اجرا نمی‌شود.

اشتراک چیست؟

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

ارسال لینک پرداخت — OrcaRail برای آن دوره یک PaymentLink می‌سازد و (به‌طور اختیاری) برای پرداخت‌کننده ایمیل می‌کند.
برداشت خودکار — پرداخت‌کننده یک بار تأیید می‌کند (allowance در EVM یا delegation در سولانا)؛ OrcaRail در هر دوره مبلغ آن دوره را برداشت می‌کند.

اشتراک‌ها از بازه‌های ثابت (روز، هفته، ماه، سال)، دوره آزمایشی اختیاری و چرخه وضعیت آشنا پشتیبانی می‌کنند.

فیلدهای رایج

مفهوم	OrcaRail
مشتری / پرداخت‌کننده	`payer` (شناسه کاربر یا ایمیل)
قلم / قیمت	`amount` + `currency` + `token_id` + `network_id` (یک قلم، بومی کریپتو)
برداشت خودکار	`collection_method: auto_charge` (برداشت با allowance در EVM یا delegation در سولانا)
صورت‌حساب / پرداخت با لینک در هر دوره	`collection_method: send_payment_link` (یک PaymentLink در هر دوره، ایمیل اختیاری)
آخرین مورد قابل پرداخت	`latest_payment_link`
چرخه وضعیت	`trialing`، `active`، `past_due`، `canceled`، `paused`، `completed` (متناسب با کریپتو)
زمان‌بندی و فراداده	`cancel_at_period_end`، `trial_end`، `billing_cycle_anchor`، `metadata`

روش‌های دریافت وجه

send_payment_link (پیش‌فرض)

در هر دوره صورت‌حساب، OrcaRail برای مبلغ اشتراک یک PaymentLink می‌سازد. می‌توانید برای پرداخت‌کننده ایمیل بفرستید (مثلاً ۱ روز پیش از سررسید). پرداخت‌کننده لینک را باز می‌کند و مثل هر پرداخت یک‌باره با کیف پولش می‌پردازد. بدون allowance و برداشت خودکار.

وقتی استفاده کنید که: می‌خواهید پرداخت‌کننده هر پرداخت را صریحاً تأیید کند، یا به برداشت خودکار نیاز ندارید.
جریان: cron صورت‌حساب PaymentLink می‌سازد ← ایمیل اختیاری ← پرداخت‌کننده از طریق اپ پرداخت میزبانی‌شده پرداخت می‌کند.

auto_charge

پرداخت‌کننده یک بار برای شبکه انتخاب‌شده تأیید می‌کند: روی EVM، یک allowance در ERC-20 برای کل مبلغ یا الگوی هر دوره؛ روی سولانا، delegation در SPL به مسیر برداشت OrcaRail. در هر دوره، job صورت‌حساب با کیف پول داغ مبلغ دوره را برداشت می‌کند (transferFrom در EVM یا انتقال دسته‌ای در سولانا).

وقتی استفاده کنید که: پرداخت دوره‌ای واقعی می‌خواهید بدون اینکه پرداخت‌کننده هر دوره لینکی باز کند.
جریان: پرداخت‌کننده در دوره اول یا صفحه اشتراک تأیید می‌کند (approval_spender_address در auto_charge را ببینید) ← در هر دوره job صورت‌حساب از پرداخت‌کننده برداشت می‌کند ← در صورت موفقیت دوره پرداخت‌شده علامت می‌خورد؛ در صورت شکست اشتراک ممکن است به past_due برود و به پرداخت‌کننده اطلاع داده شود.

برای جریان تأیید، گام‌های پرداخت‌کننده برای تأیید یا لغو و جزئیات API، برداشت خودکار را ببینید.

شیء اشتراک (ساختار پاسخ)

پاسخ‌ها از snake_case استفاده می‌کنند و این ساختار اشتراک را دارند:

{
  "id": "sub_550e8400e29b41d4a716446655440000",
  "object": "subscription",
  "status": "active",
  "collection_method": "send_payment_link",
  "amount": "10.00",
  "currency": "usd",
  "description": "Monthly Pro Plan",
  "token": { "id": "...", "symbol": "USDC", "name": "USD Coin" },
  "network": { "id": "...", "name": "Base", "chain_id": 8453 },
  "interval": "month",
  "interval_count": 1,
  "total_cycles": 12,
  "completed_cycles": 3,
  "billing_cycle_anchor": 1679609767,
  "current_period_start": "2025-03-01T00:00:00Z",
  "current_period_end": "2025-04-01T00:00:00Z",
  "start_date": "2025-01-01T00:00:00Z",
  "cancel_at": null,
  "cancel_at_period_end": false,
  "trial_start": null,
  "trial_end": null,
  "auto_charge": null,
  "payer": { "id": "...", "email": "[email protected]" },
  "latest_payment_link": {
    "id": "...",
    "unique_slug": "...",
    "link": "...",
    "status": "completed"
  },
  "withdrawal_addresses": { "evm": "0x742d..." },
  "metadata": {},
  "created": "2025-01-01T00:00:00Z",
  "updated": "2025-03-15T00:00:00Z"
}

وقتی collection_method برابر auto_charge باشد، شیء auto_charge شامل کیف پول پرداخت‌کننده و شناسه‌های توکن/شبکه، allowance_tx_hash اختیاری، approved_amount، approved_iterations، approval_spender_address (spender یا delegateی که پرداخت‌کننده باید روی زنجیره تأیید کند) و status است. برای اندپوینت‌های تأیید، لغو و تنظیم روش دریافت، برداشت خودکار را ببینید.

نمونه ساختار پس از تأیید:

"auto_charge": {
  "payer_wallet_address": "0x...",
  "payer_network_id": "...",
  "payer_token_id": "...",
  "allowance_tx_hash": "0x...",
  "approved_amount": "120.00",
  "approved_iterations": 12,
  "approval_spender_address": "0x...",
  "status": "approved"
}

چرخه وضعیت

وضعیت	توضیح
`trialing`	در دوره آزمایشی؛ تا پایان دوره آزمایشی پرداختی لازم نیست
`active`	فعال؛ در هر دوره لینک پرداخت ساخته می‌شود یا برداشت خودکار اجرا می‌شود
`past_due`	پرداخت یک دوره ناموفق بوده یا سررسیدش گذشته است
`canceled`	اشتراک پایان یافته (فوری یا در پایان دوره)
`paused`	متوقف (مثلاً پس از دوره آزمایشی بدون روش پرداخت)
`completed`	همه دوره‌ها تمام شده‌اند (`total_cycles` رسیده است)

جریان دوره صورت‌حساب

قدم‌های بعدی

ساخت اشتراک — اولین اشتراک خود را با API بسازید
مدیریت اشتراک‌ها — ویرایش، لغو، ازسرگیری، فهرست
برداشت خودکار — جریان برداشت در EVM و سولانا و اندپوینت‌های پرداخت‌کننده
وب‌هوک‌های اشتراک — انواع رویداد و payloadها
دوره‌های آزمایشی — دوره آزمایشی و رفتار آن

اشتراک چیست؟​

فیلدهای رایج​

روش‌های دریافت وجه​

send_payment_link (پیش‌فرض)​

auto_charge​

شیء اشتراک (ساختار پاسخ)​

چرخه وضعیت​

جریان دوره صورت‌حساب​

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