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

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

:::note اشتراک‌های غیرامانی

OrcaRail در حال انتقال برداشت خودکار به مدلی کاملاً غیرامانی است: spender در approve از کیف پول داغ متعلق به OrcaRail به قرارداد عمومی SubscriptionHub (EVM) یا برنامه Anchor به نام subscription (سولانا) منتقل می‌شود. جریان پرداخت‌کننده در این صفحه (یک بار تأیید، لغو در هر زمان) تغییری نمی‌کند؛ فقط آدرس spender عوض می‌شود. نمای کلی غیرامانی و مرحله ۲: اشتراک مبتنی بر allowance را ببینید.

:::

برای پرداخت‌کنندگان: چطور تأیید و چطور لغو کنید

این بخش برای کسانی است که هزینه اشتراک را می‌پردازند (مشتریان)، نه توسعه‌دهندگانی که API را یکپارچه می‌کنند.

با چه چیزی موافقت می‌کنید

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

چطور برداشت خودکار را تأیید کنید

1. لینکی را که کسب‌وکار فرستاده باز کنید (ایمیل، وب‌سایت یا اپ). باید شما را به صفحه پرداخت یا اشتراک میزبانی‌شده OrcaRail ببرد.
2. کیف پولتان را روی شبکه درست وصل کنید و توکن نمایش‌داده‌شده (مثلاً USDC) را انتخاب کنید.
3. خلاصه را بخوانید: قیمت هر دوره، هر چند وقت یک بار برداشت می‌شود و مجموع یا تعداد دوره‌هایی که تأیید پوشش می‌دهد.
4. وقتی برای فعال کردن برداشت خودکار کلیک می‌کنید، کیف پول از شما می‌خواهد مجوز توکن را تأیید (approve) کنید. فقط اگر با مبالغ و کسب‌وکار موافقید تأیید کنید.
5. پس از تأیید تراکنش روی زنجیره، پیام موفقیت را می‌بینید. سپس OrcaRail تأیید را ثبت می‌کند؛ دوره‌های بعدی به‌طور خودکار برداشت می‌شوند تا وقتی تأیید تمام شود، شکست بخورد (مثلاً به‌خاطر موجودی کم) یا آن را لغو کنید.

اگر چیزی شکست خورد، بررسی کنید روی شبکه و توکن درست هستید، سپس دوباره امتحان کنید یا اگر فروشنده امکانش را داده، آن دوره را با لینک پرداخت بپردازید.

چطور برداشت خودکار را لغو کنید (توقف برداشت‌های خودکار)

1. روی زنجیره لغو کنید تا spender دیگر نتواند توکن‌هایتان را برداشت کند:
   • EVM: تراکنشی بفرستید که allowance را حذف کند؛ معمولاً approve(spender, 0) روی قرارداد توکن برای آدرس spender اورکاریل (ابزارهای «مجوزهای توکن» یا لغو مجوز در کیف پول ممکن است این را ارائه دهند).
   • سولانا: delegation توکن SPL را که برای آن اشتراک داده‌اید لغو کنید.
2. اگر فروشنده جریانی ارائه داده، آن را کامل کنید (مثلاً «مدیریت اشتراک» ← توقف برداشت خودکار). این به OrcaRail می‌گوید شما را به‌جای برداشت به لینک پرداخت در هر دوره منتقل کند، و ممکن است ایمیلی با گام‌های بعدی دریافت کنید.
3. اگر فقط روی زنجیره لغو کنید و هرگز به OrcaRail اطلاع ندهید، برداشت خودکار بعدی ممکن است شکست بخورد و اشتراک تا پرداخت لینک یا اصلاح تأیید سررسیدگذشته شود.

فروشندگان و اپ‌های سفارشی پس از لغو روی زنجیره از لغو برداشت خودکار (API) استفاده می‌کنند.

چطور کار می‌کند

1. فروشنده اشتراکی با collection_method: "auto_charge" می‌سازد.
2. پرداخت‌کننده لینک اشتراک یا لینک پرداخت دوره اول را باز می‌کند (یا در موارد لازم از طریق تنظیم روش دریافت برداشت خودکار را انتخاب می‌کند).
3. پرداخت‌کننده تأیید روی زنجیره را کامل می‌کند: approve(spender, amount) در EVM به آدرس spender اورکاریل، یا delegation معادل SPL در سولانا. از approval_spender_address در شیء auto_charge اشتراک (در صورت وجود) به‌عنوان spender/delegateی که کیف پول باید تأیید کند استفاده کنید.
4. پرداخت‌کننده تأیید را به OrcaRail ارسال می‌کند: POST /api/v1/subscriptions/:id/approve-auto-charge با allowance_tx_hash، payer_wallet_address، payer_network_id، payer_token_id و در صورت تمایل approved_amount / approved_iterations.
5. OrcaRail allowance را ثبت و auto_charge را تأییدشده علامت می‌زند. در هر دوره صورت‌حساب، job صورت‌حساب با کیف پول داغ مبلغ دوره را برداشت می‌کند. در صورت موفقیت دوره پرداخت‌شده علامت می‌خورد و دوره صورت‌حساب جلو می‌رود؛ در صورت شکست اشتراک ممکن است به past_due برود و به پرداخت‌کننده اطلاع داده شود.

تأیید برداشت خودکار (پرداخت‌کننده)

POST /api/v1/subscriptions/:id/approve-auto-charge

این اندپوینت عمومی (سمت پرداخت‌کننده) است. کلید API فروشنده لازم نیست؛ پرداخت‌کننده با امضای تراکنش تأیید روی زنجیره قصدش را ثابت کرده است.

بدنه درخواست

پارامتر	نوع	الزامی	توضیح
payer_wallet_address	string	بله	آدرس کیف پول پرداخت‌کننده (EVM یا سولانا، بسته به شبکه)
payer_network_id	string (UUID)	بله	شناسه شبکه‌ای که allowance یا delegation روی آن تنظیم شده
payer_token_id	string (UUID)	بله	شناسه توکن (مثلاً USDC)
allowance_tx_hash	string	بله	هش تراکنش تأیید (approve در EVM یا تنظیم SPL در سولانا، بسته به مورد)
approved_amount	string	خیر	کل مبلغ تأییدشده (مثلاً "120.00" برای دوازده برداشت ماهانه)
approved_iterations	integer	خیر	تعداد دوره‌های صورت‌حساب که آن مجموع پوشش می‌دهد (مثلاً 12). اگر هر دو approved_amount و approved_iterations تنظیم شوند، OrcaRail می‌تواند مبلغ برداشت هر دوره را محاسبه کند.

جریان در اپ پرداخت

1. خلاصه اشتراک را نشان دهید: توضیح، مبلغ هر دوره، بازه، تعداد کل دوره‌ها و مبلغ کل قابل تأیید.
2. approval_spender_address را از auto_charge اشتراک (یا payload اشتراک) بخوانید تا کیف پول spender/delegate درست را تأیید کند.
3. «تأیید» باعث می‌شود کیف پول تأیید متناسب با زنجیره را امضا کند (مثلاً wagmi/viem روی EVM).
4. پس از تأیید تراکنش، POST .../approve-auto-charge را با هش تراکنش و اطلاعات پرداخت‌کننده/شبکه/توکن (و در صورت تمایل approved_amount / approved_iterations) فراخوانی کنید.
5. در صورت موفقیت نشان دهید: «برداشت خودکار تأیید شد. [مبلغ] [بازه] به‌طور خودکار از شما برداشت می‌شود.»

لغو برداشت خودکار (پرداخت‌کننده)

پس از لغو روی زنجیره (EVM: approve(spender, 0)؛ سولانا: لغو delegation در SPL)، پرداخت‌کننده می‌تواند آن را به OrcaRail اعلام کند:

POST /api/v1/subscriptions/:id/revoke-auto-charge

این اندپوینت مثل تأیید عمومی (سمت پرداخت‌کننده) است.

بدنه درخواست

پارامتر	نوع	الزامی	توضیح
payer_wallet_address	string	بله	کیف پولی که allowance یا delegation را داشت
revocation_tx_hash	string	بله	هش تراکنش لغو روی زنجیره

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

تنظیم روش دریافت (پرداخت‌کننده)

پرداخت‌کنندگان می‌توانند از جریان میزبانی‌شده انتخاب کنند چطور بپردازند (لینک پرداخت در هر دوره یا برداشت خودکار):

POST /api/v1/subscriptions/:id/set-collection-method

عمومی (سمت پرداخت‌کننده). کلید API فروشنده لازم نیست.

بدنه درخواست

پارامتر	نوع	الزامی	توضیح
collection_method	string	بله	send_payment_link یا auto_charge
payer_wallet_id	string (UUID)	برای auto_charge	شناسه کیف پول تأییدشده پرداخت‌کننده که برای برداشت استفاده می‌شود
payer_network_id	string (UUID)	خیر	شبکه انتخابی پرداخت‌کننده برای برداشت خودکار؛ اگر حذف شود شبکه اشتراک استفاده می‌شود
payer_token_id	string (UUID)	خیر	توکن انتخابی پرداخت‌کننده برای برداشت خودکار؛ اگر حذف شود توکن اشتراک استفاده می‌شود

شیء کامل اشتراک را برمی‌گرداند (همان ساختار دریافت).

شیء auto_charge در اشتراک

وقتی collection_method برابر auto_charge باشد، پاسخ اشتراک شامل این است:

{
  "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"
  }
}

• approval_spender_address — آدرس (EVM) یا شناسه معادلی که پرداخت‌کننده باید به‌عنوان spender/delegate برای برداشت روی آن شبکه تأیید کند.
• approved_iterations — اگر همراه approved_amount تنظیم شود، مشخص می‌کند آن تأیید یکجا چند دوره را پوشش می‌دهد.

status می‌تواند این‌ها باشد: pending، approved، revoked، failed. اگر پرداخت‌کننده روی زنجیره لغو کند ممکن است revoked ببینید؛ اگر برداشت مکرراً شکست بخورد، failed یا اشتراک past_due.

مدیریت شکست

• شکست برداشت (مثلاً موجودی ناکافی یا لغو allowance/delegation): اشتراک ممکن است به past_due برود و پرداخت‌کننده ایمیل دریافت کند (مثلاً اعلان شکست برداشت خودکار). می‌توانید به وب‌هوک‌های subscription.payment_link.payment_failed یا subscription.past_due گوش دهید.
• پرداخت‌کننده بدون فراخوانی API روی زنجیره لغو می‌کند: برداشت‌های بعدی شکست می‌خورند؛ اشتراک ممکن است تا وقتی از پرداخت‌کننده بخواهید دوباره تأیید کند یا روش دریافت را عوض کند past_due شود.
• پرداخت‌کننده لغو را از طریق API تأیید می‌کند (لغو برداشت خودکار): OrcaRail اشتراک را به send_payment_link تغییر می‌دهد و برای پرداخت‌کننده ایمیل می‌فرستد.

امنیت و تجربه کاربری

• فقط از کیف پولی که تأیید را انجام داده می‌توان برداشت کرد؛ بک‌اند allowance یا delegation را روی زنجیره بررسی می‌کند.
• مبلغ کل تأیید و تعداد برداشت‌ها را واضح نشان دهید تا پرداخت‌کننده بداند چه چیزی را تأیید می‌کند.
• برای اشتراک‌های بسیار طولانی یا نامحدود، محدود کردن مبلغ تأییدشده (مثلاً ۱۲ ماه) و درخواست تأیید دوباره در آینده را در نظر بگیرید، یا از send_payment_link استفاده کنید.

قدم‌های بعدی

• ساخت اشتراک — از collection_method: "auto_charge" استفاده کنید
• وب‌هوک‌های اشتراک — subscription.payment_link.payment_failed، subscription.past_due
• مدیریت اشتراک‌ها — اگر پرداخت‌کننده به لینک پرداخت رفت، ویرایش یا لغو کنید
• اشتراک‌ها (SDK) — SDKهای فروشنده؛ تأیید/لغو/تنظیم روش دریافت پرداخت‌کننده از طریق HTTP در صفحه پرداخت میزبانی‌شده