Cara Tambah Langganan dengan Stripe: Pelan, Percubaan, Webhook dan Pembayaran Gagal
Untuk menambah langganan dengan Stripe, cipta produk dengan harga berulang dalam Stripe Dashboard, hantar pelanggan ke Stripe Checkout dalam mod langganan dari pelayan anda, dan biarkan webhook memberitahu aplikasi anda apabila setiap pembayaran berjaya, gagal, berubah atau tamat. Simpan status langganan berbanding pengguna dan berikan akses berdasarkannya, bukan daripada halaman kejayaan. Tambah butang Urus bil yang membuka portal pelanggan yang dihoskan Stripe supaya orang boleh menukar kad, bertukar pelan dan membatalkan tanpa anda membina skrin tersebut.
Panduan ini dibina atas cara menambah pembayaran pada aplikasi anda, yang meliputi Checkout sekali, mod ujian dan pelancaran. Di sini kita fokus pada apa yang berbeza tentang bil berulang. Butiran Stripe adalah daripada dokumentasi Stripe setakat September 2026.
Mengapa langganan lebih sukar daripada pembayaran sekali
Pembayaran sekali berlaku ketika pelanggan berada dalam aplikasi anda. Langganan terus berlaku selepas mereka pergi: pembaharuan setiap bulan, kad yang tamat tempoh, peningkatan di pertengahan kitaran, pembatalan yang berkuat kuasa pada akhir tempoh. Aplikasi anda hanya mengetahui perkara ini melalui webhook. Kebanyakan pepijat langganan berpunca daripada menganggap pembayaran pertama sebagai keseluruhan cerita.
Pilihan anda
| Pendekatan | Apa yang anda bina | Sesuai untuk |
|---|---|---|
| Payment Link dengan harga berulang | Tiada selain pautan | Menguji permintaan; mengendalikan akses secara manual |
| Checkout (mod langganan) + portal pelanggan | Laluan pelayan, webhook, butang bil | Kebanyakan aplikasi SaaS dan keahlian |
| API langganan dengan borang pembayaran sendiri | Jauh lebih banyak: UI pembayaran, pengesahan, cubaan semula | Aplikasi dengan aliran bil yang luar biasa |
| Pembekal pedagang rekod | Serupa dengan Checkout | Penjual yang mahu pembekal mengendalikan cukai jualan |
Bagi kebanyakan aplikasi, Checkout ditambah portal ialah pertukaran yang tepat. Bandingkan pembekal dalam Stripe vs Paddle vs Lemon Squeezy jika pengendalian cukai membimbangkan anda.
Rancang harga anda dalam Stripe dahulu
Dalam Stripe, produk ialah apa yang anda jual ("Pelan Pro") dan harga ialah cara anda mengenakan caj untuknya ("$20 sebulan", "$200 setahun"). Satu produk boleh mempunyai beberapa harga. Tentukan:
- Tahap mana yang anda tawarkan dan apa yang dibuka oleh setiap tahap dalam aplikasi anda
- Bulanan, tahunan, atau kedua-duanya
- Sama ada anda menawarkan percubaan, dan sama ada ia memerlukan kad di awal
Cipta produk dan harga dalam mod ujian, dan simpan ID harga mereka; aplikasi anda merujuk kepadanya. Jika anda belum menetapkan harga, baca cara menetapkan harga produk SaaS dan freemium vs percubaan percuma.
Kitaran hayat langganan yang perlu anda kendalikan
Gambaran keseluruhan langganan Stripe menyenaraikan status yang boleh dimiliki oleh langganan. Yang paling penting untuk akses ialah:
| Status | Maksudnya | Berikan akses? |
|---|---|---|
trialing | Dalam tempoh percubaan | Ya |
active | Dalam keadaan baik | Ya |
incomplete | Pembayaran pertama belum selesai; Stripe memberi pelanggan 23 jam | Tidak |
incomplete_expired | Pembayaran pertama tidak pernah berjaya | Tidak |
past_due | Pembayaran terkini gagal atau tidak dicuba; percubaan semula mungkin menyusul | Pilihan anda; ramai aplikasi membenarkan tempoh tangguh yang pendek |
unpaid | Percubaan semula tamat, invois kekal terbuka, tiada percubaan lanjut | Tidak; dokumentasi Stripe menyarankan akses ditarik balik |
canceled | Tamat; tidak boleh dimulakan semula | Tidak |
paused | Percubaan tamat tanpa kaedah pembayaran dan ditetapkan untuk dijeda | Tidak |
Simpan status pada rekod pengguna atau akaun anda dan asaskan akses padanya. Kemas kini setiap kali webhook yang berkaitan tiba.
Peristiwa webhook yang perlu dikendalikan
| Peristiwa | Apa yang aplikasi anda lakukan |
|---|---|
checkout.session.completed | Pautkan ID pelanggan dan langganan Stripe yang baharu kepada pengguna anda |
invoice.paid | Tandakan langganan sebagai aktif dan rekodkan tarikh tamat tempoh baharu |
invoice.payment_failed | Beritahu pengguna bahawa kad mereka gagal dan pautkan ke portal |
invoice.payment_action_required | Minta pengguna melengkapkan pengesahan kad |
customer.subscription.updated | Kemas kini pelan, status, dan sebarang pembatalan yang dijadualkan |
customer.subscription.deleted | Alih keluar akses berbayar |
customer.subscription.trial_will_end | Ingatkan pengguna sebelum percubaan tamat; Stripe menghantarnya tiga hari lebih awal |
Peraturan pengendali daripada dokumentasi webhook Stripe masih terpakai: sahkan tandatangan menggunakan badan mentah, pulangkan 2xx dengan cepat, kendalikan peristiwa pendua dan tidak mengikut urutan, dan jangkakan percubaan semula. Panduan apa itu webhook menerangkan ideanya, dan panduan pembayaran menyenaraikan peraturan dengan terperinci.
Langkah demi langkah
- Cipta produk dan harga dalam mod ujian Stripe.
- Tambah rahsia: kunci rahsia, ID harga, dan kemudian rahsia penandatanganan webhook. Jangan sekali-kali letakkannya dalam kod bahagian hadapan.
- Halaman harga: setiap butang pelan memanggil pelayan anda, yang mencipta Checkout Session dalam mod langganan untuk pengguna yang log masuk. Hantar ID pengguna anda supaya webhook dapat memadankan pembayaran dengan akaun.
- Titik akhir webhook: sahkan tandatangan dan kendalikan peristiwa di atas, mengemas kini satu rekod langganan bagi setiap pengguna.
- Hadkan ciri berdasarkan status dan pelan yang disimpan, disemak di pelayan untuk setiap tindakan dilindungi, bukan sekadar butang tersembunyi.
- Portal pelanggan: konfigurasikannya dalam Stripe Dashboard (pelan mana yang boleh ditukar, sama ada mereka boleh membatalkan), kemudian tambah butang Urus bil yang mencipta sesi portal di pelayan dan mengalihkan ke sana.
- Pembayaran gagal: dalam tetapan bil Stripe, pilih kelakuan cubaan semula dan apa yang berlaku selepas percubaan terakhir. Papar sepanduk dalam aplikasi semasa
past_due. - Uji keseluruhan kitaran hayat, kemudian terbitkan dan daftarkan webhook sebenar.
Prompt untuk diberikan kepada pembina AI anda
Tambah bil langganan dengan Stripe. Pelan: Starter (ID harga dalam STRIPE_PRICE_STARTER) dan Pro (STRIPE_PRICE_PRO). Halaman harga mencipta Checkout Session dalam mod langganan di pelayan menggunakan STRIPE_SECRET_KEY, dengan ID pengguna yang log masuk dilampirkan. Simpan ID pelanggan Stripe, ID langganan, pelan dan status pada pengguna. Jangan sekali-kali dedahkan kunci rahsia kepada pelayar.
Tambah POST /api/stripe/webhook. Sahkan tandatangan dengan STRIPE_WEBHOOK_SECRET menggunakan badan permintaan mentah. Kendalikan checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted dan customer.subscription.trial_will_end. Rekodkan ID peristiwa yang diproses supaya pendua diabaikan. Kemas kini status pengguna daripada objek langganan, bukan daripada urutan peristiwa tiba.
Hadkan ciri Pro di pelayan: benarkan hanya apabila status ialah active atau trialing dan pelannya Pro. Papar sepanduk "pembayaran gagal, kemas kini kad anda" apabila status ialah past_due. Tambah butang Urus bil yang membuka portal pelanggan Stripe untuk pengguna ini.
Peningkatan, penurunan dan prorata
Apabila pelanggan bertukar pelan, dokumentasi Stripe menyatakan perubahan itu sering mencipta prorata: harga baharu digunakan untuk baki tempoh bil semasa. Anda boleh pratonton prorata atau mematikannya. Jika pelan mempunyai selang yang sama, tarikh bil kekal sama; beralih dari bulanan ke tahunan memindahkan tarikh bil ke hari pertukaran. Membenarkan pelanggan menukar pelan dalam portal menjimatkan anda daripada menulis logik ini, tetapi tentukan dalam tetapan portal pertukaran mana yang dibenarkan.
Senarai semak ujian
Gunakan mod ujian Stripe dan kad ujian, dan lalui setiap status:
- Langganan baharu memberikan pelan yang betul kepada pengguna yang betul
- Menutup tab sejurus selepas membayar masih memberi akses (membuktikan webhook berfungsi)
- Kad yang ditolak semasa pendaftaran tidak memberi apa-apa
- Pembaharuan yang gagal meletakkan akaun dalam past_due dan memaparkan sepanduk
- Mengemas kini kad dalam portal memulihkan status active
- Peningkatan dan penurunan menukar ciri dengan betul
- Membatalkan pada akhir tempoh mengekalkan akses sehingga tarikh tamat, kemudian mengalihkannya
- Pengguna percubaan mendapat akses, menerima peringatan, dan bertukar atau kehilangan akses dengan betul
- Menghantar peristiwa webhook yang sama dua kali tidak mengubah apa-apa
Jam ujian Stripe membolehkan anda mensimulasikan masa yang berlalu, supaya anda boleh menguji pembaharuan tanpa menunggu sebulan. Semak dokumentasi ujian semasa Stripe untuk cara menggunakannya.
Kesilapan biasa
- Memberi akses pada halaman kejayaan. Pelanggan mungkin membayar dan tidak pernah sampai ke sana. Gunakan webhook.
- Hanya mengendalikan pembayaran pertama. Pembaharuan, kegagalan dan pembatalan tiba kemudian, sebagai peristiwa.
- Menyemak status pelan hanya di bahagian hadapan. Sesiapa sahaja boleh memanggil API anda secara langsung.
- Satu pengguna, banyak langganan secara tidak sengaja. Semak langganan sedia ada sebelum mencipta Checkout Session baharu, atau hantar pelanggan sedia ada ke portal.
- Menarik balik akses pada kegagalan pembaharuan pertama. Kad gagal atas sebab yang membosankan. Tempoh tangguh pendek dengan sepanduk yang jelas mengekalkan pelanggan.
- Terlupa webhook sebenar. Titik akhir ujian dan sebenar mempunyai rahsia penandatanganan yang berbeza.
- Mengabaikan cukai dan bayaran balik. Tentukan dasar bayaran balik anda dan semak kewajipan cukai dengan akauntan sebelum pelancaran.
Langganan dalam Mythex
Aplikasi yang anda bina pada Mythex menggunakan akaun dan kunci Stripe anda sendiri; tiada sambungan Stripe satu klik untuk aplikasi anda. Tambah kunci ujian dan ID harga anda sebagai rahsia projek, gunakan prompt seperti di atas, dan uji dengan kad ujian Stripe dalam Pratonton. Webhook memerlukan URL awam aplikasi anda, jadi terbitkan sebelum mendaftarkan titik akhir dalam Stripe, dan terbitkan semula selepas beralih ke kunci sebenar supaya aplikasi sebenar mengambilnya. Lihat Terima pembayaran dengan Stripe dan Kendalikan webhook dalam bahagian belakang anda. Untuk gambaran produk yang lebih luas, cara membina MVP SaaS meliputi apa yang perlu dibina di sekeliling bil.
Soalan lazim
Apakah cara paling ringkas untuk menambah langganan dengan Stripe?
Cipta produk dengan harga berulang dalam Stripe Dashboard, hantar pelanggan ke Stripe Checkout dalam mod langganan, kendalikan peristiwa langganan dengan webhook, dan pautkan butang Urus bil ke portal pelanggan yang dihoskan Stripe. Dengan itu anda tidak perlu membina sendiri borang kad dan skrin tukar pelan.
Apakah peristiwa webhook Stripe yang saya perlukan untuk langganan?
Sekurang-kurangnya checkout.session.completed untuk memautkan langganan baharu kepada pengguna anda, invoice.paid untuk mengesahkan setiap pembayaran berjaya, invoice.payment_failed untuk memberi amaran tentang pembaharuan yang gagal, serta customer.subscription.updated dan customer.subscription.deleted untuk menjejak perubahan pelan dan pembatalan.
Apakah yang berlaku apabila pembayaran langganan gagal?
Menurut dokumentasi Stripe setakat September 2026, langganan biasanya bertukar kepada past_due dan Stripe boleh mencuba semula pembayaran mengikut tetapan anda. Selepas percubaan terakhir, tetapan Dashboard anda menentukan sama ada ia dibatalkan, ditandakan unpaid, atau dibiarkan past_due.
Bolehkah saya tawarkan percubaan percuma tanpa meminta kad?
Boleh. Stripe menyokong percubaan percuma, dan dokumentasinya menerangkan status paused untuk percubaan yang tamat tanpa kaedah pembayaran apabila ia dikonfigurasikan begitu. Meminta kad di awal biasanya bermakna lebih sedikit pendaftaran tetapi lebih ramai pelanggan berbayar; uji apa yang sesuai dengan produk anda.