پرش به مطلب اصلی

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

اشتراک‌ها می‌توانند دوره آزمایشی داشته باشند که در آن پرداختی لازم نیست. وقتی دوره آزمایشی تمام شود، اولین دوره صورت‌حساب شروع می‌شود و طبق collection_method از پرداخت‌کننده برداشت می‌شود (یا لینک پرداخت برایش فرستاده می‌شود).

دوره آزمایشی چطور کار می‌کند​

  • trial_period_days — هنگام ساخت تنظیم می‌شود؛ اشتراک در وضعیت trialing شروع می‌شود. به تعداد روزهای تعیین‌شده از زمان ساخت، وجهی دریافت نمی‌شود.
  • trial_end — زمان ISO اختیاری برای تعیین صریح پایان دوره آزمایشی. همچنین می‌توانید trial_end: "now" را بگذارید تا عملاً بدون دوره آزمایشی شروع شود.
  • وقتی دوره آزمایشی تمام می‌شود:
    • اگر collection_method برابر send_payment_link باشد: برای اولین دوره لینک پرداخت ساخته می‌شود و (در صورت تنظیم) برای پرداخت‌کننده ایمیل فرستاده می‌شود.
    • اگر collection_method برابر auto_charge باشد: پرداخت‌کننده باید پیش از پایان دوره آزمایشی یا در همان زمان allowance را تأیید کرده باشد؛ در غیر این صورت اشتراک ممکن است تا تأیید او به paused برود.
  • subscription.trial_will_end — OrcaRail این وب‌هوک را حدود ۳ روز پیش از trial_end می‌فرستد تا بتوانید به پرداخت‌کننده یادآوری کنید روش پرداخت اضافه کند یا برداشت خودکار را تأیید کند.

ساخت اشتراک با دوره آزمایشی​

هنگام ساخت اشتراک از trial_period_days (یا trial_end) استفاده کنید:

POST /api/v1/subscriptions
{
  "description": "Pro Plan",
  "amount": "10.00",
  "currency": "usd",
  "token_id": "...",
  "network_id": "...",
  "interval": "month",
  "trial_period_days": 14,
  "payer_email": "[email protected]"
}

پاسخ شامل این موارد است:

  • status: "trialing"
  • trial_start: برابر زمان ساخت
  • trial_end: برابر زمان ساخت + ۱۴ روز
  • current_period_start / current_period_end: اولین دوره صورت‌حساب پس از دوره آزمایشی

ویرایش پایان دوره آزمایشی​

می‌توانید trial_end یک اشتراک موجود را تغییر دهید (مثلاً برای تمدید یا کوتاه کردن دوره آزمایشی):

PATCH /api/v1/subscriptions/:id
{
  "trial_end": "2025-04-15T00:00:00Z"
}

برای پایان فوری دوره آزمایشی و شروع اولین دوره صورت‌حساب از "now" استفاده کنید.

جریان وضعیت با دوره آزمایشی​

  • trialing — هنوز برداشتی انجام نشده؛ trial_end در آینده است.
  • پس از trial_end: وقتی اولین دوره پرداخت شود اشتراک به active می‌رود (یا اگر روش پرداخت / allowance نباشد به paused).

وب‌هوک‌ها​

  • subscription.created — هنگام ساخت اشتراک ارسال می‌شود (ممکن است trialing باشد).
  • subscription.trial_will_end — حدود ۳ روز پیش از trial_end ارسال می‌شود؛ برای ایمیل به پرداخت‌کننده یا درخواست تأیید برداشت خودکار از آن استفاده کنید.
  • subscription.payment_link.created — وقتی اولین لینک پرداخت پس از دوره آزمایشی ساخته می‌شود (برای send_payment_link).
  • subscription.payment_link.paid — وقتی اولین دوره پس از دوره آزمایشی پرداخت می‌شود.

بهترین روش‌ها​

  1. پیش از پایان دوره آزمایشی یادآوری کنید — subscription.trial_will_end را پردازش کنید تا ایمیل یا پیام درون‌برنامه‌ای بفرستید.
  2. برداشت خودکار و دوره آزمایشی — برای auto_charge، پرداخت‌کننده را راهنمایی کنید تا پیش از trial_end allowance را تأیید کند تا اولین برداشت موفق شود؛ در غیر این صورت اشتراک ممکن است paused یا past_due شود.
  3. پیام روشن — در صفحه پرداخت یا اشتراک، طول دوره آزمایشی و تاریخ و مبلغ اولین برداشت را نشان دهید تا پرداخت‌کننده بداند چه انتظاری داشته باشد.

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