ساخت اشتراک

برای شروع دریافت پرداخت‌های دوره‌ای از یک پرداخت‌کننده، اشتراک بسازید.

اندپوینت

POST /api/v1/subscriptions

احراز هویت

نیازمند احراز هویت پرداخت است: توکن Bearer (JWT) یا کلید API (Basic).

بدنه درخواست (snake_case)

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

پارامتر	نوع	الزامی	توضیح
description	string	بله	توضیح اشتراک (مثلاً «پلن ماهانه Pro»)
amount	string	بله	مبلغ هر دوره صورت‌حساب (مثلاً "10.00")
currency	string	بله	کد سه‌حرفی ISO ارز (مثلاً usd)
token_id	string	بله	شناسه توکن دریافتی (مثلاً USDC)
network_id	string	بله	شناسه شبکه دریافت
interval	string	بله	بازه صورت‌حساب: day، week، month، year
interval_count	number	خیر	تعداد بازه‌ها در هر دوره (پیش‌فرض 1)
collection_method	string	خیر	send_payment_link (پیش‌فرض) یا auto_charge
total_cycles	number	خیر	تعداد کل دوره‌های صورت‌حساب؛ برای نامحدود حذف یا null کنید
billing_cycle_anchor	string	خیر	زمان ISO شروع اولین دوره
cancel_at	string	خیر	زمان ISO لغو
cancel_at_period_end	boolean	خیر	اگر true باشد، در پایان دوره فعلی لغو می‌شود
days_until_due	number	خیر	تعداد روز پس از پایان دوره تا سررسیدگذشته تلقی شود
trial_end	string	خیر	زمان ISO پایان دوره آزمایشی (یا "now" برای رد شدن از آن)
trial_period_days	number	خیر	تعداد روزهای آزمایشی از زمان ساخت
payer_user_id	string	خیر	شناسه کاربری پرداخت‌کننده ثبت‌نام‌شده
payer_email	string	خیر	ایمیل پرداخت‌کننده برای اعلان‌ها و لینک‌های پرداخت
withdrawal_addresses	object	خیر	کلیدها: نوع زنجیره (مثلاً evm)، مقدار: آدرس
metadata	object	خیر	فراداده کلید-مقدار

پاسخ

شیء کامل اشتراک را برمی‌گرداند (نمای کلی را ببینید) با status، current_period_start، current_period_end و (برای send_payment_link) لینک پرداخت دوره اول در صورت وجود.

نمونه‌ها

cURL

curl -X POST https://api.orcarail.com/api/v1/subscriptions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Monthly Pro Plan",
    "amount": "10.00",
    "currency": "usd",
    "token_id": "uuid-for-usdc",
    "network_id": "uuid-for-base",
    "interval": "month",
    "interval_count": 1,
    "collection_method": "send_payment_link",
    "total_cycles": 12,
    "payer_email": "[email protected]"
  }'

JavaScript (fetch)

const response = await fetch('https://api.orcarail.com/api/v1/subscriptions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${jwtToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    description: 'Monthly Pro Plan',
    amount: '10.00',
    currency: 'usd',
    token_id: tokenId,
    network_id: networkId,
    interval: 'month',
    interval_count: 1,
    collection_method: 'send_payment_link',
    total_cycles: 12,
    payer_email: '[email protected]',
    metadata: { plan_id: 'pro_monthly' },
  }),
})

const subscription = await response.json()
console.log('Subscription ID:', subscription.id)
console.log('Current period end:', subscription.current_period_end)

با دوره آزمایشی

{
  "description": "Pro Plan with trial",
  "amount": "10.00",
  "currency": "usd",
  "token_id": "...",
  "network_id": "...",
  "interval": "month",
  "trial_period_days": 14,
  "payer_email": "[email protected]"
}

برداشت خودکار

{
  "description": "Yearly Pro (auto-charge)",
  "amount": "100.00",
  "currency": "usd",
  "token_id": "...",
  "network_id": "...",
  "interval": "year",
  "collection_method": "auto_charge",
  "total_cycles": 1,
  "payer_email": "[email protected]"
}

با auto_charge، پرداخت‌کننده باید بعداً allowance در ERC-20 را تأیید کند (برداشت خودکار را ببینید).

قدم‌های بعدی

• مدیریت اشتراک‌ها — ویرایش، لغو، ازسرگیری، فهرست
• برداشت خودکار — جریان تأیید allowance
• وب‌هوک‌های اشتراک — به رویدادهای اشتراک واکنش نشان دهید