چطور پرداخت به اپ اضافه کنیم: تسویه‌حساب، اشتراک و وب‌هوک
ساده‌ترین راه برای افزودن پرداخت به اپ، Stripe است: اگر فقط یک دکمه «خرید» می‌خواهید و می‌توانید سفارش‌ها را دستی انجام دهید، از Payment Link استفاده کنید؛ اگر اپ باید بداند چه کسی پرداخت کرده و خودکار واکنش نشان دهد، از Stripe Checkout استفاده کنید؛ و برای صورتحساب تکرارشونده، Checkout در حالت اشتراک به‌همراه پورتال مشتری Stripe. در هر حالتی به جز ساده‌ترین، به یک وب‌هوک هم نیاز دارید؛ یک endpoint سروری که Stripe وقتی پرداخت موفق شد صدایش می‌زند. و همه‌چیز را با کلیدها و کارت‌های آزمایشی Stripe تست کنید، قبل از اینکه به کلیدهای واقعی تغییر دهید.
این راهنما هر گزینه، بخش وب‌هوک که بیشتر آموزش‌ها از کنارش رد می‌شوند، و چیزهایی که قبل از دریافت پول واقعی باید بررسی کنید را توضیح می‌دهد. جزئیات Stripe از مستندات خود Stripe و از سپتامبر ۲۰۲۶ است.
چرا اصلاً از یک ارائه‌دهنده پرداخت استفاده کنیم
هرگز شماره کارت را در فرم‌های خودتان جمع نکنید. کار با داده کارت شما را در دامنه PCI DSS (استاندارد امنیتی صنعت کارت) قرار می‌دهد و مسئولیت بزرگی است. یک ارائه‌دهنده پرداخت مثل Stripe فرم پرداخت را میزبانی می‌کند، کارت را ذخیره می‌کند، احراز هویت بانکی را انجام می‌دهد و نتیجه را به اپ شما می‌گوید. اپ شما فقط «مشتری X برای Y پرداخت کرد» را می‌بیند.
این راهنما از Stripe استفاده می‌کند چون گسترده به کار می‌رود، مستندات خوبی دارد و بیشتر ساز اپ‌های هوش مصنوعی از آن پشتیبانی می‌کنند. ارائه‌دهندگان دیگری هم وجود دارند و بعضی‌شان به‌عنوان «تاجر ثبت‌شده» (merchant of record) عمل می‌کنند و مدیریت مالیات فروش را برعهده می‌گیرند؛ اگر انطباق مالیاتی نگرانتان می‌کند، این مدل ارزش مقایسه دارد.
سه راه دریافت پرداخت با Stripe
| گزینه | نیاز به کد | اپ می‌داند چه کسی پرداخت کرده؟ | بهترین کاربرد |
|---|---|---|---|
| Payment Links | ندارد | فقط اگر وب‌هوک اضافه کنید | فروش چند محصول ثابت، کمک مالی، سنجش تقاضا |
| Checkout (یک‌باره) | کد سروری برای ساخت session | بله، با وب‌هوک | فروشگاه‌ها، دانلود پولی، خریدهای یک‌باره |
| Checkout (اشتراک) | کد سروری به‌همراه مدیریت وب‌هوک | بله، با وب‌هوک | SaaS، عضویت، هر چیز تکرارشونده |
Payment Links
Payment Link یک صفحه پرداخت میزبانی‌شده توسط Stripe است که بدون کد در داشبورد Stripe می‌سازید. یک URL می‌گیرید که می‌توانید پشت یک دکمه در اپ بگذارید، در ایمیل به اشتراک بگذارید یا به‌صورت QR code نشان دهید. مستندات Stripe می‌گوید Payment Links می‌توانند یک محصول، یک اشتراک را بفروشند یا کمک مالی بپذیرند، و می‌توانید به مشتری اجازه دهید انتخاب کند چه چیزی پرداخت کند یا تعداد خریدها را محدود کنید.
نکته‌ی منفی: اپ شما به‌طور خودکار نمی‌داند کاربر واردشده خاصی پرداخت کرده است. برای یک صفحه کمک مالی یا فروشگاه کوچکی که سفارش‌ها را از روی ایمیل‌های Stripe دستی انجام می‌دهید، کافی است. برای «برای باز کردن امکانات Pro پرداخت کنید»، کافی نیست.
Stripe Checkout
Checkout یک صفحه پرداخت است که سرور شما برای یک خرید مشخص، در لحظه، می‌سازد. سرور به Stripe می‌گوید چه چیزی خریده می‌شود (و در صورت تمایل کدام مشتری می‌خرد)، Stripe یک URL برمی‌گرداند و شما مشتری را به آنجا می‌فرستید. مستندات Stripe آن را پشتیبان پرداخت یک‌باره و اشتراک معرفی می‌کند، به‌صورت صفحه کامل میزبانی‌شده توسط Stripe، صفحه‌ای که در سایت شما جاسازی شده، یا فرم جاسازی‌شده.
روند کار:
- مشتری در اپ شما روی خرید کلیک می‌کند.
- سرور شما با استفاده از کلید مخفی‌تان یک Checkout Session می‌سازد، شامل شناسه‌ای که آن را به کاربر یا سفارش شما متصل می‌کند.
- مشتری به Stripe هدایت می‌شود و پرداخت می‌کند.
- Stripe او را به صفحه موفقیت شما برمی‌گرداند.
- Stripe رویداد
checkout.session.completedرا به وب‌هوک شما می‌فرستد و سرور شما سفارش را پرداخت‌شده علامت می‌زند یا دسترسی را باز می‌کند.
مرحله ۲ باید روی سرور انجام شود، چون از کلید مخفی شما استفاده می‌کند. این اصلی‌ترین دلیل است که Checkout به بک‌اند نیاز دارد.
اشتراک‌ها
اشتراک‌ها از Checkout در حالت اشتراک با یک قیمت تکرارشونده که در Stripe تعریف کرده‌اید استفاده می‌کنند. پرداخت اول دقیقاً مثل جریان بالاست. بعد از آن، تمدیدها، کارت‌های ناموفق، ارتقا در میانه دوره و لغوها در طول زمان رخ می‌دهند، اغلب وقتی مشتری دیگر در اپ شما نیست، پس اپ شما فقط از طریق وب‌هوک‌ها از آن‌ها باخبر می‌شود.
برای اینکه مشتری بتواند اشتراک خودش را مدیریت کند، Stripe یک پورتال مشتری میزبانی‌شده ارائه می‌دهد. طبق مستندات Stripe، مشتریان می‌توانند روش پرداخت و جزئیات صورتحساب را به‌روز کنند، اشتراک را تغییر دهند یا لغو کنند، و فاکتورها را ببینند و دانلود کنند. آن را در داشبورد Stripe پیکربندی می‌کنید و یک دکمه «مدیریت صورتحساب» اضافه می‌کنید که مشتری را به آنجا می‌فرستد. این کار ساختن آن صفحه‌ها را از شما می‌گیرد.
وب‌هوک‌ها: بخشی که نمی‌توانید از آن بگذرید
وب‌هوک یک درخواست HTTP است که Stripe وقتی اتفاقی می‌افتد به سرور شما می‌فرستد. (برای ایده کلی، وب‌هوک چیست را ببینید.) راهنمای تکمیل سفارش Stripe صریح است: نمی‌توانید فقط به صفحه موفقیت برای تکمیل سفارش تکیه کنید، چون مشتری ممکن است پرداخت کند و قبل از بارگذاری آن صفحه اتصالش قطع شود. برای اشتراک‌ها و روش‌های پرداخت با تأخیر، وب‌هوک‌ها الزامی‌اند.
رویدادهایی که باید مدیریت شوند
| رویداد | معنی آن | کار اپ شما |
|---|---|---|
checkout.session.completed | Checkout تمام شد | سفارش را پرداخت‌شده علامت بزنید یا دسترسی را شروع کنید |
checkout.session.async_payment_succeeded | یک روش با تأخیر (مثل برداشت بانکی) بعداً تأیید شد | همین حالا تکمیل کنید |
checkout.session.async_payment_failed | آن پرداخت با تأخیر ناموفق شد | به مشتری بگویید؛ تکمیل نکنید |
invoice.paid | پرداخت اشتراک موفق بود، شامل تمدیدها | دسترسی را تمدید کنید |
invoice.payment_failed | یک تمدید ناموفق بود | به کاربر هشدار دهید؛ Stripe ممکن است دوباره تلاش کند |
customer.subscription.updated | طرح عوض شد، یا لغو زمان‌بندی شد | طرح کاربر را به‌روز کنید |
customer.subscription.deleted | اشتراک تمام شد | دسترسی پولی را حذف کنید |
قوانین یک هندلر درست وب‌هوک
این‌ها مستقیم از مستندات وب‌هوک Stripe آمده‌اند و هندلرهای تولیدشده با هوش مصنوعی گاهی یکی از آن‌ها را جا می‌اندازند:
- امضا را تأیید کنید. هر رویداد هدر
Stripe-Signatureدارد. هندلر شما آن را با سِکرِت امضای endpoint بررسی می‌کند (که باwhsec_شروع می‌شود). بدون این، هر کسی می‌توانست یک «پرداخت موفق» جعلی به سرور شما بفرستد. - بدنه خام درخواست را استفاده کنید. بررسی امضا شکست می‌خورد اگر فریم‌ورک بدنه را قبل از آن تجزیه یا تغییر دهد.
- سریع یک پاسخ 2xx برگردانید، بعد کارهای کندتر را انجام دهید. timeout هم شکست حساب می‌شود.
- تکرار را مدیریت کنید. Stripe ممکن است همان رویداد را بیش از یک بار بفرستد. شناسه رویدادهای پردازش‌شده را ثبت کنید، یا تکمیل سفارش را طوری بنویسید که دوبار اجرا شدنش بی‌خطر باشد.
- ترتیب را فرض نکنید. Stripe تضمین نمی‌کند رویدادها به ترتیب وقوعشان برسند.
- انتظار تلاش مجدد داشته باشید. در حالت واقعی، Stripe تحویل‌های ناموفق را تا سه روز دوباره تلاش می‌کند، پس یک قطعی کوتاه پرداختی را گم نمی‌کند، اما هندلر شما باید با رویدادهای دیرهنگام کنار بیاید.
وب‌هوک‌ها به یک آدرس عمومی HTTPS نیاز دارند، پس معمولاً فقط بعد از منتشر شدن اپ کار می‌کنند (ابزار CLI تحت وب Stripe می‌تواند رویدادها را به دستگاه محلی توسعه‌دهنده فوروارد کند).
یک درخواست که کل جریان را پوشش می‌دهد
یک خرید یک‌باره با Stripe Checkout برای «بسته Pro» (شناسه قیمت در STRIPE_PRICE_ID) اضافه کن. Checkout Session را روی سرور با STRIPE_SECRET_KEY از رازها بساز و شناسه کاربر واردشده را در session قرار بده. یک endpoint به نام POST /api/stripe/webhook اضافه کن که امضای Stripe را با STRIPE_WEBHOOK_SECRET و بدنه خام درخواست تأیید کند، checkout.session.completed را مدیریت کند و آن کاربر را دارای «بسته Pro» علامت بزند. اگر همان رویداد دوبار برسد، امن باشد. صفحات موفقیت و لغو اضافه کن. هرگز کلید مخفی را به مرورگر نشان نده.
برای اشتراک‌ها اضافه کنید: «از حالت اشتراک با STRIPE_PRICE_ID استفاده کن. invoice.paid، invoice.payment_failed، customer.subscription.updated و customer.subscription.deleted را مدیریت کن. یک دکمه مدیریت صورتحساب اضافه کن که پورتال مشتری Stripe را برای این کاربر باز کند.»
حالت تست
Stripe محیط‌های جدا برای آزمایش (sandbox) و واقعی دارد، با کلیدهای جدا. کلیدهای آزمایشی با pk_test_، sk_test_ یا rk_test_ شروع می‌شوند؛ کلیدهای واقعی با pk_live_، sk_live_ یا rk_live_. تراکنش‌های تست پول جابه‌جا نمی‌کنند.
کارت‌های آزمایشی مفید از مستندات تست Stripe (هر تاریخ انقضای آینده، هر CVC سه‌رقمی):
| شماره کارت | نتیجه |
|---|---|
4242 4242 4242 4242 | پرداخت موفق است |
4000 0000 0000 0002 | کارت رد می‌شود |
4000 0000 0000 3220 | نیاز به احراز 3D Secure دارد، سپس موفق است |
حداقل این موارد را تست کنید:
- یک پرداخت موفق، چیز درست را برای کاربر درست باز می‌کند
- یک کارت ردشده پیام واضح نشان می‌دهد و چیزی باز نمی‌کند
- بستن تب مرورگر بلافاصله بعد از پرداخت هم منجر به دسترسی می‌شود (این ثابت می‌کند وب‌هوک کار می‌کند، نه فقط صفحه موفقیت)
- لغو در صفحه Stripe کاربر را به اپ برمی‌گرداند بدون هیچ مبلغی کسر شده
- برای اشتراک‌ها: در پورتال مشتری لغو کنید و تأیید کنید دسترسی سر موقع تمام می‌شود
انتشار واقعی
- حساب Stripe خود را فعال کنید با جزئیات کسب‌وکار و بانکی.
- کلیدهای واقعی را در رازهای اپ قرار دهید. Stripe کلیدهای محدودشده (restricted) با فقط مجوزهای لازم را به‌جای کلید مخفی نامحدود توصیه می‌کند.
- یک endpoint وب‌هوک واقعی بسازید که به اپ منتشرشده شما اشاره کند. سِکرِت امضای جدا دارد، متفاوت از نسخه تست؛ آن را به‌روز کنید.
- محصولات و قیمت‌ها را در حالت واقعی دوباره بسازید؛ شناسه‌های حالت تست در آنجا وجود ندارند.
- یک خرید واقعی کوچک انجام دهید و آن را بازپرداخت کنید.
هر کلیدی را در رازهای پروژه نگه دارید، نه در کد یا چت. چک‌لیست امنیتی ما کلیدها و تأیید وب‌هوک را با جزئیات بیشتری پوشش می‌دهد.
مالیات، بازپرداخت و کارهای اداری
پرداخت تعهداتی می‌آورد که کد آن‌ها را حل نمی‌کند. این مشاوره مالیاتی نیست؛ با حسابدار مشورت کنید.
- مالیات فروش، ارزش افزوده و GST. بسته به محل شما و مشتریانتان، ممکن است نیاز باشد ثبت‌نام کنید، مالیات دریافت و اظهار کنید. Stripe Tax می‌تواند مالیات را در تسویه‌حساب محاسبه و جمع‌آوری کند، نشان دهد فروش‌هایتان کجا تعهد ایجاد می‌کند، و در ثبت‌نام و اظهار کمک کند، اما مسئولیت با شما می‌ماند. ارائه‌دهندگان «تاجر ثبت‌شده» گزینه‌ای هستند که بیشتری از این‌ها را برعهده می‌گیرند.
- بازپرداخت و اختلاف‌ها. قبل از انتشار سیاست بازپرداخت خود را تعیین و روی سایت بگذارید. اختلاف‌ها (chargeback) پیش می‌آیند؛ سوابق آنچه خریده و تحویل شده را نگه دارید.
- رسید و فاکتور. Stripe می‌تواند رسید ایمیل کند؛ کسب‌وکارها ممکن است به فاکتور درست نیاز داشته باشند.
- کارمزد. هر ارائه‌دهنده برای هر تراکنش کارمزد می‌گیرد. به صفحه قیمت فعلی ارائه‌دهنده نگاه کنید، نه به ارقام موجود در مقالات.
کدام تنظیم برای اپ شما مناسب است
- کمک مالی یا چند محصول محدود: Payment Links. نحوه ساخت وب‌سایت کمک مالی غیرانتفاعی را ببینید.
- فروشگاه با سبد خرید: Checkout با اقلام سفارش و وب‌هوک. نحوه ساخت فروشگاه آنلاین را ببینید.
- SaaS یا عضویت: Checkout در حالت اشتراک، وب‌هوک‌ها و پورتال مشتری. نحوه ساخت MVP سَس و نحوه قیمت‌گذاری محصول SaaS را ببینید.
- بازاری که به فروشندگان پرداخت می‌کند: یک تنظیم متفاوت و سخت‌گیرانه‌تر (Stripe Connect یا مشابه). جداگانه برنامه‌ریزی کنید.
افزودن پرداخت در Mythex
پرداخت‌ها در اپ‌هایی که با Mythex می‌سازید از حساب و کلیدهای خودتان در Stripe استفاده می‌کنند؛ برای اپ شما اتصال یک‌کلیکی «Connect Stripe» وجود ندارد. روند معمول:
- کلیدهای تست Stripe را بگیرید.
STRIPE_SECRET_KEY(و بعداً سِکرِت وب‌هوک) را به رازهای پروژه اضافه کنید؛ از طریق/secrets، تنظیمات پروژه یا کارت رازهایی که عامل وقتی به کلیدی نیاز دارد نشان می‌دهد.- از عامل بخواهید Checkout را با درخواستی مانند بالا بسازد.
- در Preview با کارت‌های تست آزمایش کنید. قبل از ثبت وب‌هوک منتشر کنید، چون به آدرس عمومی شما نیاز دارد.
- بعد از تغییر به کلیدهای واقعی، دوباره منتشر کنید تا اپ واقعی آن‌ها را بگیرد.
به پذیرش پرداخت با Stripe و مدیریت وب‌هوک‌ها در بک‌اند در مستندات نگاه کنید.
پرسش‌ها
ساده‌ترین راه دریافت پرداخت در یک اپ چیست؟
یک Stripe Payment Link بدون کد کار می‌کند: آن را در داشبورد Stripe می‌سازید و از اپ به آن پیوند می‌دهید. اگر اپ شما باید بداند چه کسی پرداخت کرده و خودکار چیزی را باز کند، از Stripe Checkout به‌همراه وب‌هوک استفاده کنید.
آیا برای دریافت پرداخت به وب‌هوک نیاز دارم؟
اگر اپ باید به یک پرداخت واکنش نشان دهد، مثلاً حساب را باز کند، سفارش را پرداخت‌شده علامت بزند یا تمدید را مدیریت کند، بله. مستندات Stripe می‌گوید نمی‌توانید فقط به صفحه موفقیت تکیه کنید، چون ممکن است مشتری پرداخت کند و هرگز به آن صفحه نرسد. وب‌هوک برای اشتراک‌ها هم الزامی است.
چطور بدون پول واقعی پرداخت را تست کنم؟
از کلیدهای API آزمایشی (sandbox) Stripe و شماره کارت‌های تست آن استفاده کنید، مثل 4242 4242 4242 4242 با هر تاریخ انقضای آینده و هر CVC سه‌رقمی. تراکنش‌های تست پول واقعی جابه‌جا نمی‌کنند.
آیا Stripe مالیات فروش و ارزش افزوده را برایم مدیریت می‌کند؟
Stripe Tax می‌تواند مالیات را در تسویه‌حساب محاسبه و جمع‌آوری کند و نشان دهد کجا ممکن است نیاز به ثبت‌نام داشته باشید، اما مسئولیت تعهدات مالیاتی با خودتان است. برای وضعیت خودتان با حسابدار مشورت کنید.