چطور اشتراک با Stripe اضافه کنیم: طرح‌ها، دوره آزمایشی، وب‌هوک و پرداخت ناموفق
برای افزودن اشتراک با Stripe، یک محصول با قیمت تکرارشونده در داشبورد Stripe بسازید، مشتریان را از سرور به Stripe Checkout در حالت اشتراک بفرستید، و بگذارید یک وب‌هوک به اپ شما بگوید هر پرداخت کی موفق، ناموفق، تغییریافته یا تمام شده است. وضعیت اشتراک را روی کاربر ذخیره کنید و دسترسی را بر اساس آن بدهید، نه بر اساس صفحه موفقیت. یک دکمه مدیریت صورتحساب اضافه کنید که پورتال میزبانی‌شده مشتری Stripe را باز کند تا مردم بتوانند کارت عوض کنند، طرح را تغییر دهند و لغو کنند، بدون اینکه شما آن صفحه‌ها را بسازید.
این راهنما بر پایه نحوه افزودن پرداخت به اپ است که Checkout یک‌باره، حالت تست و انتشار واقعی را پوشش می‌دهد. اینجا روی آنچه صورتحساب تکرارشونده را متفاوت می‌کند تمرکز می‌کنیم. جزئیات Stripe از مستندات Stripe و از سپتامبر ۲۰۲۶ است.
چرا اشتراک‌ها سخت‌تر از پرداخت‌های یک‌باره‌اند
یک پرداخت یک‌باره وقتی مشتری داخل اپ شماست اتفاق می‌افتد. یک اشتراک بعد از رفتن او هم ادامه دارد: تمدید هر ماه، کارت‌هایی که منقضی می‌شوند، ارتقا در میانه دوره، لغوهایی که در پایان دوره اعمال می‌شوند. اپ شما فقط از طریق وب‌هوک‌ها از اینها باخبر می‌شود. بیشتر باگ‌های اشتراک از این می‌آیند که پرداخت اول را کل داستان فرض کنیم.
گزینه‌های شما
| روش | آنچه می‌سازید | مناسب برای |
|---|---|---|
| Payment Link با قیمت تکرارشونده | فقط یک پیوند | سنجش تقاضا؛ مدیریت دسترسی به‌صورت دستی |
| Checkout (حالت اشتراک) + پورتال مشتری | یک route سروری، یک وب‌هوک، یک دکمه صورتحساب | بیشتر اپ‌های SaaS و عضویت‌ها |
| Subscriptions API با فرم پرداخت خودتان | بسیار بیشتر: رابط پرداخت، احراز، تلاش مجدد | اپ‌هایی با جریان‌های صورتحساب غیرمعمول |
| ارائه‌دهنده تاجر ثبت‌شده | شبیه Checkout | فروشندگانی که می‌خواهند ارائه‌دهنده مالیات فروش را مدیریت کند |
برای بیشتر اپ‌ها، Checkout به‌همراه پورتال تعادل مناسبی است. اگر مالیات برایتان نگران‌کننده است، Stripe در برابر Paddle در برابر Lemon Squeezy را مقایسه کنید.
اول قیمت‌گذاری را در Stripe تعیین کنید
در Stripe، یک محصول چیزی است که می‌فروشید («طرح Pro») و یک قیمت روش شارژ آن است («۲۰ دلار در ماه»، «۲۰۰ دلار در سال»). یک محصول می‌تواند چند قیمت داشته باشد. تصمیم بگیرید:
- چه سطوحی ارائه می‌دهید و هر کدام در اپ چه چیزی را باز می‌کند
- ماهانه، سالانه، یا هر دو
- آیا دوره آزمایشی دارید، و آیا برای آن کارت از ابتدا لازم است
محصولات و قیمت‌ها را در حالت تست بسازید و شناسه قیمت‌ها را نگه دارید؛ اپ شما به آن‌ها ارجاع می‌دهد. اگر قیمت‌گذاری هنوز تعیین نشده، نحوه قیمت‌گذاری محصول SaaS و فری‌میوم در برابر دوره آزمایشی رایگان را بخوانید.
چرخه عمر اشتراک که باید مدیریت کنید
اشتراک‌های Stripe وضعیت‌هایی دارند که در نمای کلی اشتراک‌های Stripe آمده است. مهم‌ترین‌ها برای دسترسی:
| وضعیت | معنی | دسترسی بدهم؟ |
|---|---|---|
trialing | در دوره آزمایشی | بله |
active | در وضعیت خوب | بله |
incomplete | پرداخت اول هنوز کامل نشده؛ Stripe ۲۳ ساعت به مشتری می‌دهد | خیر |
incomplete_expired | پرداخت اول هرگز موفق نشد | خیر |
past_due | آخرین پرداخت ناموفق بود یا امتحان نشد؛ ممکن است تلاش‌های مجدد بیایند | انتخاب شما؛ بسیاری از اپ‌ها یک مهلت کوتاه می‌دهند |
unpaid | تلاش‌های مجدد تمام شد، فاکتورها باز می‌مانند، دیگر تلاشی نیست | خیر؛ مستندات Stripe می‌گوید دسترسی باید لغو شود |
canceled | تمام شد؛ قابل شروع مجدد نیست | خیر |
paused | یک دوره آزمایشی بدون روش پرداخت تمام شد و طوری تنظیم شده بود که متوقف شود | خیر |
وضعیت را روی رکورد کاربر یا حساب ذخیره کنید و دسترسی را بر اساس آن قرار دهید. هر بار که وب‌هوک مرتبطی می‌رسد آن را به‌روز کنید.
رویدادهای وب‌هوک که باید مدیریت شوند
| رویداد | کار اپ شما |
|---|---|
checkout.session.completed | شناسه‌های مشتری و اشتراک جدید Stripe را به کاربرتان وصل کنید |
invoice.paid | اشتراک را فعال علامت بزنید و پایان دوره جدید را ثبت کنید |
invoice.payment_failed | به کاربر بگویید کارتش ناموفق بود و پیوند پورتال بدهید |
invoice.payment_action_required | از کاربر بخواهید احراز هویت کارت را کامل کند |
customer.subscription.updated | طرح، وضعیت و هر لغو زمان‌بندی‌شده را به‌روز کنید |
customer.subscription.deleted | دسترسی پولی را حذف کنید |
customer.subscription.trial_will_end | قبل از پایان دوره آزمایشی یادآوری بدهید؛ Stripe سه روز قبل آن را می‌فرستد |
قوانین هندلر از مستندات وب‌هوک Stripe همچنان برقرارند: امضا را با بدنه خام تأیید کنید، سریع یک پاسخ 2xx برگردانید، رویدادهای تکراری و خارج از ترتیب را مدیریت کنید، و انتظار تلاش مجدد داشته باشید. راهنمای وب‌هوک چیست ایده را توضیح می‌دهد و راهنمای پرداخت قوانین را با جزئیات فهرست کرده است.
مرحله به مرحله
- محصولات و قیمت‌ها را در حالت تست Stripe بسازید.
- رازها را اضافه کنید: کلید مخفی، شناسه‌های قیمت، و بعداً سِکرِت امضای وب‌هوک. هرگز آن‌ها را در کد فرانت‌اند نگذارید.
- صفحه قیمت‌ها: دکمه هر طرح یک درخواست به سرور می‌فرستد، که یک Checkout Session در حالت اشتراک برای کاربر واردشده می‌سازد. شناسه کاربر خود را ضمیمه کنید تا وب‌هوک پرداخت را به حساب درست تطبیق دهد.
- endpoint وب‌هوک: امضاها را تأیید کنید و رویدادهای بالا را مدیریت کنید، و یک رکورد اشتراک برای هر کاربر به‌روز کنید.
- دسترسی به امکانات را بر اساس وضعیت و طرح ذخیره‌شده بدهید، و آن را برای هر کار محافظت‌شده روی سرور بررسی کنید، نه فقط دکمه‌های پنهان.
- پورتال مشتری: آن را در داشبورد Stripe پیکربندی کنید (مشتری به کدام طرح‌ها می‌تواند برود، آیا می‌تواند لغو کند)، سپس یک دکمه مدیریت صورتحساب اضافه کنید که یک session پورتال روی سرور می‌سازد و هدایت می‌کند.
- پرداخت‌های ناموفق: در تنظیمات صورتحساب Stripe، رفتار تلاش مجدد و اتفاق بعد از آخرین تلاش را انتخاب کنید. وقتی
past_dueاست یک بنر داخل اپ نشان دهید. - کل چرخه عمر را تست کنید، سپس منتشر کنید و وب‌هوک واقعی را ثبت کنید.
درخواست‌هایی برای ساز اپ هوش مصنوعی
صورتحساب اشتراک با Stripe اضافه کن. طرح‌ها: Starter (شناسه قیمت در STRIPE_PRICE_STARTER) و Pro (STRIPE_PRICE_PRO). صفحه قیمت‌ها یک Checkout Session در حالت اشتراک را روی سرور با STRIPE_SECRET_KEY می‌سازد و شناسه کاربر واردشده را ضمیمه می‌کند. شناسه مشتری Stripe، شناسه اشتراک، طرح و وضعیت را روی کاربر ذخیره کن. هرگز کلید مخفی را به مرورگر نشان نده.
یک POST /api/stripe/webhook اضافه کن. امضا را با STRIPE_WEBHOOK_SECRET و بدنه خام درخواست تأیید کن. checkout.session.completed، invoice.paid، invoice.payment_failed، customer.subscription.updated، customer.subscription.deleted و customer.subscription.trial_will_end را مدیریت کن. شناسه رویدادهای پردازش‌شده را ثبت کن تا تکرارها نادیده گرفته شوند. وضعیت کاربر را از شیء اشتراک به‌روز کن، نه از ترتیب رسیدن رویدادها.
ویژگی‌های Pro را روی سرور گیت کن: فقط وقتی وضعیت active یا trialing و طرح Pro است اجازه بده. وقتی وضعیت past_due است، یک بنر «پرداخت ناموفق بود، کارت را به‌روز کنید» نشان بده. یک دکمه مدیریت صورتحساب اضافه کن که پورتال مشتری Stripe را برای این کاربر باز کند.
ارتقا، کاهش طرح و تناسب
وقتی مشتری طرح را عوض می‌کند، مستندات Stripe می‌گوید این تغییر اغلب یک proration (تناسب) ایجاد می‌کند: قیمت جدید برای بقیه دوره صورتحساب جاری اعمال می‌شود. می‌توانید proration ها را پیش‌نمایش کنید یا خاموش کنید. اگر طرح‌ها بازه یکسانی دارند، تاریخ‌های صورتحساب ثابت می‌مانند؛ از ماهانه به سالانه، تاریخ صورتحساب به روز تغییر می‌رسد. اجازه دادن به مشتریان برای تغییر طرح در پورتال، نوشتن این منطق را از شما می‌گیرد، اما باید در تنظیمات پورتال تعیین کنید کدام تغییرها مجازند.
چک‌لیست تست
از حالت تست Stripe و کارت‌های آزمایشی استفاده کنید و هر وضعیت را طی کنید:
- اشتراک جدید طرح درست را به کاربر درست می‌دهد
- بستن تب بلافاصله بعد از پرداخت هم دسترسی می‌دهد (این ثابت می‌کند وب‌هوک کار می‌کند)
- یک کارت ردشده هنگام ثبت‌نام هیچ دسترسی نمی‌دهد
- تمدیدی که ناموفق است، حساب را به past_due می‌برد و بنر را نشان می‌دهد
- به‌روزرسانی کارت در پورتال، وضعیت active را برمی‌گرداند
- ارتقا و کاهش طرح، امکانات را درست تغییر می‌دهند
- لغو در پایان دوره، دسترسی را تا تاریخ پایان نگه می‌دارد و بعد حذف می‌کند
- کاربران دوره آزمایشی دسترسی دارند، یادآوری می‌گیرند، و درست تبدیل می‌شوند یا دسترسی را از دست می‌دهند
- فرستادن دوباره همان رویداد وب‌هوک هیچ تغییری ایجاد نمی‌کند
تست‌های ساعت Stripe (test clocks) اجازه می‌دهند زمان گذشتن را شبیه‌سازی کنید، تا تمدیدها را بدون انتظار یک ماه تست کنید. برای نحوه استفاده از آن‌ها، مستندات تست فعلی Stripe را بررسی کنید.
اشتباهات رایج
- دادن دسترسی در صفحه موفقیت. مشتریان ممکن است پرداخت کنند و هرگز به آن صفحه نرسند. از وب‌هوک استفاده کنید.
- فقط مدیریت پرداخت اول. تمدیدها، ناموفق‌ها و لغوها به‌صورت رویداد بعداً می‌رسند.
- بررسی وضعیت طرح فقط در فرانت‌اند. هر کسی می‌تواند مستقیم API شما را صدا بزند.
- یک کاربر، چند اشتراک به‌طور تصادفی. قبل از ساختن یک Checkout Session جدید، وجود اشتراک موجود را بررسی کنید، یا مشتریان موجود را به پورتال بفرستید.
- لغو دسترسی با اولین تمدید ناموفق. کارت‌ها به دلایل پیش‌پاافتاده رد می‌شوند. یک مهلت کوتاه با بنر واضح مشتری را نگه می‌دارد.
- فراموش کردن وب‌هوک واقعی. endpoint تست و واقعی سِکرِت امضای متفاوت دارند.
- نادیده گرفتن مالیات و بازپرداخت. قبل از انتشار، سیاست بازپرداخت را تعیین کنید و تعهدات مالیاتی را با حسابدار بررسی کنید.
اشتراک در Mythex
اپ‌هایی که روی Mythex می‌سازید از حساب و کلیدهای خودتان در Stripe استفاده می‌کنند؛ برای اپ شما اتصال یک‌کلیکی به Stripe وجود ندارد. کلیدهای تست و شناسه قیمت‌هایتان را به‌عنوان رازهای پروژه اضافه کنید، از درخواست‌های بالا استفاده کنید و با کارت‌های تست Stripe در Preview آزمایش کنید. وب‌هوک‌ها به آدرس عمومی اپ شما نیاز دارند، پس قبل از ثبت endpoint در Stripe منتشر کنید، و بعد از تغییر به کلیدهای واقعی دوباره منتشر کنید تا اپ واقعی آن‌ها را بگیرد. به پذیرش پرداخت با Stripe و مدیریت وب‌هوک‌ها در بک‌اند نگاه کنید. برای کل محصول، نحوه ساخت MVP سَس نشان می‌دهد چه چیزی باید دور صورتحساب ساخته شود.
پرسش‌ها
ساده‌ترین راه افزودن اشتراک با Stripe چیست؟
در داشبورد Stripe یک محصول با قیمت تکرارشونده بسازید، مشتریان را با Stripe Checkout در حالت اشتراک از سرور به آنجا بفرستید، رویدادهای اشتراک را با وب‌هوک مدیریت کنید و یک دکمه «مدیریت صورتحساب» به پورتال میزبانی‌شده مشتری Stripe وصل کنید. این کار نیاز به ساختن فرم کارت و صفحه‌های تغییر طرح را از بین می‌برد.
برای اشتراک‌ها به کدام رویدادهای وب‌هوک Stripe نیاز دارم؟
حداقل checkout.session.completed برای وصل کردن اشتراک جدید به کاربرتان، invoice.paid برای تأیید هر پرداخت موفق، invoice.payment_failed برای هشدار درباره تمدیدهای ناموفق، و customer.subscription.updated و customer.subscription.deleted برای پیگیری تغییر طرح و لغوها.
وقتی پرداخت اشتراک ناموفق می‌شود چه اتفاقی می‌افتد؟
طبق مستندات Stripe از سپتامبر ۲۰۲۶، معمولاً وضعیت اشتراک به past_due می‌رود و Stripe بر اساس تنظیماتتان ممکن است پرداخت را دوباره امتحان کند. بعد از آخرین تلاش، تنظیمات داشبورد شما تعیین می‌کند آیا لغو شود، به‌عنوان پرداخت‌نشده علامت بخورد، یا در وضعیت past_due بماند.
آیا می‌توانم دوره آزمایشی رایگان بدهم بدون اینکه کارت بخواهم؟
بله. Stripe دوره‌های آزمایشی رایگان را پشتیبانی می‌کند و در مستندات آن وضعیت paused برای دوره‌هایی که بدون روش پرداخت تمام می‌شوند، وقتی به این شکل تنظیم شده باشد، توضیح داده شده است. گرفتن کارت از ابتدا معمولاً ثبت‌نام کمتر، اما مشتری پولی بیشتر می‌آورد؛ آنچه با محصولتان جور است را آزمایش کنید.