Cara Menambahkan Langganan dengan Stripe: Paket, Uji Coba, Webhook, dan Pembayaran Gagal
Untuk menambahkan langganan dengan Stripe, buat produk dengan harga berulang di Dashboard Stripe, kirim pelanggan ke Stripe Checkout dalam mode langganan dari server kamu, dan biarkan webhook memberi tahu aplikasi kamu saat setiap pembayaran berhasil, gagal, berubah, atau berakhir. Simpan status langganan terhadap pengguna dan berikan akses berdasarkan status itu, bukan dari halaman sukses. Tambahkan tombol Kelola tagihan yang membuka portal pelanggan Stripe yang dihosting, sehingga orang bisa mengganti kartu, berpindah paket, dan membatalkan tanpa kamu harus membangun layar-layar itu.
Panduan ini melanjutkan cara menambahkan pembayaran ke aplikasi, yang membahas Checkout sekali bayar, mode uji, dan go live. Di sini kita fokus pada apa yang berbeda dari tagihan berulang. Detail Stripe berasal dari dokumentasi Stripe per September 2026.
Mengapa langganan lebih sulit daripada pembayaran sekali
Pembayaran sekali terjadi saat pelanggan berada di aplikasi kamu. Langganan terus berjalan setelah mereka pergi: perpanjangan setiap bulan, kartu yang kedaluwarsa, peningkatan di tengah periode, dan pembatalan yang berlaku di akhir periode. Aplikasi kamu hanya mengetahui hal-hal ini lewat webhook. Sebagian besar bug langganan muncul dari memperlakukan pembayaran pertama sebagai keseluruhan cerita.
Pilihanmu
| Pendekatan | Yang kamu bangun | Cocok untuk |
|---|---|---|
| Payment Link dengan harga berulang | Hanya sebuah tautan | Menguji minat pasar; menangani akses secara manual |
| Checkout (mode langganan) + portal pelanggan | Rute server, webhook, tombol tagihan | Sebagian besar aplikasi SaaS dan keanggotaan |
| API langganan dengan formulir pembayaran sendiri | Jauh lebih banyak: UI pembayaran, autentikasi, percobaan ulang | Aplikasi dengan alur tagihan yang tidak biasa |
| Penyedia merchant-of-record | Mirip dengan Checkout | Penjual yang ingin penyedia menangani pajak penjualan |
Untuk sebagian besar aplikasi, Checkout ditambah portal adalah pilihan yang tepat. Bandingkan penyedia di Stripe vs Paddle vs Lemon Squeezy jika penanganan pajak menjadi kekhawatiran.
Rencanakan harga di Stripe terlebih dahulu
Di Stripe, produk adalah apa yang kamu jual ("Paket Pro") dan harga adalah cara kamu menagihnya ("$20 per bulan", "$200 per tahun"). Satu produk bisa punya beberapa harga. Tentukan:
- Tingkatan apa yang kamu tawarkan dan apa yang dibuka setiap tingkatan di aplikasi kamu
- Bulanan, tahunan, atau keduanya
- Apakah kamu menawarkan uji coba, dan apakah itu membutuhkan kartu di awal
Buat produk dan harga dalam mode uji, dan simpan ID harganya; aplikasi kamu merujuk ke sana. Jika kamu belum menentukan harga, baca cara menetapkan harga produk SaaS dan freemium vs uji coba gratis.
Siklus hidup langganan yang harus kamu tangani
Ringkasan subscription Stripe mencantumkan status yang bisa dimiliki langganan. Yang paling penting untuk akses:
| Status | Artinya | Berikan akses? |
|---|---|---|
trialing | Dalam periode uji coba | Ya |
active | Dalam kondisi baik | Ya |
incomplete | Pembayaran pertama belum selesai; Stripe memberi pelanggan 23 jam | Tidak |
incomplete_expired | Pembayaran pertama tidak pernah berhasil | Tidak |
past_due | Pembayaran terakhir gagal atau belum dicoba; percobaan ulang mungkin menyusul | Pilihanmu; banyak aplikasi memberi masa tenggang singkat |
unpaid | Percobaan ulang selesai, invoice tetap terbuka, tidak ada percobaan lagi | Tidak; dokumentasi Stripe menyarankan mencabut akses |
canceled | Berakhir; tidak bisa dimulai lagi | Tidak |
paused | Uji coba berakhir tanpa metode pembayaran dan diatur untuk dijeda | Tidak |
Simpan status di catatan pengguna atau akunmu dan jadikan akses berdasarkan status itu. Perbarui setiap kali webhook yang relevan datang.
Event webhook yang perlu ditangani
| Event | Yang dilakukan aplikasi kamu |
|---|---|
checkout.session.completed | Tautkan ID pelanggan dan langganan Stripe yang baru ke pengguna kamu |
invoice.paid | Tandai langganan aktif dan catat akhir periode yang baru |
invoice.payment_failed | Beri tahu pengguna bahwa kartunya gagal dan tautkan ke portal |
invoice.payment_action_required | Minta pengguna menyelesaikan autentikasi kartu |
customer.subscription.updated | Perbarui paket, status, dan pembatalan terjadwal apa pun |
customer.subscription.deleted | Hapus akses berbayar |
customer.subscription.trial_will_end | Ingatkan pengguna sebelum uji coba berakhir; Stripe mengirimnya tiga hari sebelumnya |
Aturan handler dari dokumentasi webhook Stripe tetap berlaku: verifikasi tanda tangan menggunakan body mentah, kembalikan respons 2xx dengan cepat, tangani duplikat dan event yang tidak berurutan, dan bersiap untuk percobaan ulang. Panduan apa itu webhook menjelaskan idenya, dan panduan pembayaran mencantumkan aturannya secara detail.
Langkah demi langkah
- Buat produk dan harga di mode uji Stripe.
- Tambahkan secret: secret key, ID harga, dan nanti signing secret webhook. Jangan pernah menaruhnya di kode frontend.
- Halaman harga: setiap tombol paket memanggil server kamu, yang membuat Checkout Session dalam mode langganan untuk pengguna yang sedang login. Sertakan ID pengguna kamu agar webhook bisa mencocokkan pembayaran dengan akun.
- Endpoint webhook: verifikasi tanda tangan dan tangani event di atas, dengan memperbarui satu catatan langganan per pengguna.
- Batasi fitur berdasarkan status dan paket yang tersimpan, diperiksa di server untuk setiap tindakan yang dilindungi, bukan hanya tombol yang disembunyikan.
- Portal pelanggan: konfigurasikan di Dashboard Stripe (paket mana yang boleh dipilih, apakah mereka boleh membatalkan), lalu tambahkan tombol Kelola tagihan yang membuat sesi portal di server dan mengalihkan ke sana.
- Pembayaran gagal: di pengaturan tagihan Stripe, pilih perilaku percobaan ulang dan apa yang terjadi setelah percobaan terakhir. Tampilkan banner di aplikasi saat
past_due. - Uji seluruh siklus hidup, lalu publikasikan dan daftarkan webhook live.
Prompt untuk AI builder kamu
Tambahkan tagihan langganan dengan Stripe. Paket: Starter (ID harga di STRIPE_PRICE_STARTER) dan Pro (STRIPE_PRICE_PRO). Halaman harga membuat Checkout Session dalam mode langganan di server menggunakan STRIPE_SECRET_KEY, dengan ID pengguna yang sedang login terlampir. Simpan ID pelanggan Stripe, ID langganan, paket, dan status di pengguna. Jangan pernah menampilkan secret key ke browser.
Tambahkan POST /api/stripe/webhook. Verifikasi tanda tangan dengan STRIPE_WEBHOOK_SECRET menggunakan body permintaan mentah. Tangani checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted, dan customer.subscription.trial_will_end. Catat ID event yang sudah diproses agar duplikat diabaikan. Perbarui status pengguna dari objek langganan, bukan dari urutan event yang datang.
Batasi fitur Pro di server: izinkan hanya saat status adalah active atau trialing dan paketnya Pro. Tampilkan banner "pembayaran gagal, perbarui kartu kamu" saat status past_due. Tambahkan tombol Kelola tagihan yang membuka portal pelanggan Stripe untuk pengguna ini.
Upgrade, downgrade, dan proration
Saat pelanggan berpindah paket, dokumentasi Stripe menyatakan perubahan sering kali membuat proration: harga baru diterapkan untuk sisa periode tagihan saat ini. Kamu bisa melihat pratinjau proration atau mematikannya. Jika kedua paket memiliki interval yang sama, tanggal tagihan tetap; berpindah dari bulanan ke tahunan memindahkan tanggal tagihan ke hari perpindahan. Membiarkan pelanggan mengubah paket di portal menghemat waktu menulis logika ini, tetapi tentukan di pengaturan portal perpindahan mana yang diizinkan.
Checklist pengujian
Gunakan mode uji Stripe dan kartu uji, lalu telusuri setiap status:
- Langganan baru memberikan paket yang tepat kepada pengguna yang tepat
- Menutup tab tepat setelah membayar tetap memberikan akses (membuktikan webhook bekerja)
- Kartu yang ditolak saat pendaftaran tidak memberikan apa pun
- Perpanjangan yang gagal membuat akun masuk ke past_due dan menampilkan banner
- Memperbarui kartu di portal mengembalikan status active
- Upgrade dan downgrade mengubah fitur dengan benar
- Pembatalan di akhir periode mempertahankan akses sampai tanggal berakhir, lalu menghapusnya
- Pengguna uji coba mendapatkan akses, menerima pengingat, dan berubah atau kehilangan akses dengan benar
- Mengirim event webhook yang sama dua kali tidak mengubah apa pun
Test clock Stripe memungkinkan kamu mensimulasikan waktu berlalu, sehingga kamu bisa menguji perpanjangan tanpa menunggu sebulan. Periksa dokumentasi pengujian Stripe terbaru untuk cara menggunakannya.
Kesalahan yang sering terjadi
- Memberikan akses di halaman sukses. Pelanggan mungkin membayar dan tidak pernah sampai ke sana. Gunakan webhook.
- Hanya menangani pembayaran pertama. Perpanjangan, kegagalan, dan pembatalan datang kemudian, sebagai event.
- Memeriksa status paket hanya di frontend. Siapa pun bisa memanggil API kamu secara langsung.
- Satu pengguna, banyak langganan karena kebetulan. Periksa apakah sudah ada langganan sebelum membuat Checkout Session baru, atau kirim pelanggan yang sudah ada ke portal.
- Mencabut akses pada perpanjangan pertama yang gagal. Kartu gagal karena alasan yang biasa saja. Masa tenggang singkat dengan banner yang jelas mempertahankan pelanggan.
- Lupa webhook live. Endpoint uji dan live memiliki signing secret yang berbeda.
- Mengabaikan pajak dan refund. Tentukan kebijakan refund dan periksa kewajiban pajakmu dengan akuntan sebelum peluncuran.
Langganan di Mythex
Aplikasi yang kamu bangun di Mythex menggunakan akun dan key Stripe milikmu sendiri; tidak ada koneksi Stripe satu klik untuk aplikasimu. Tambahkan key uji dan ID harga sebagai secret proyek, gunakan prompt seperti di atas, dan uji dengan kartu uji Stripe di Preview. Webhook membutuhkan URL publik aplikasimu, jadi publikasikan sebelum mendaftarkan endpoint di Stripe, dan publikasikan lagi setelah beralih ke key live agar aplikasi live memakainya. Lihat Terima pembayaran dengan Stripe dan Tangani webhook di backend kamu. Untuk produk secara keseluruhan, cara membangun MVP SaaS membahas apa yang dibangun di sekitar tagihan.
Pertanyaan
Apa cara termudah untuk menambahkan langganan dengan Stripe?
Buat produk dengan harga berulang di Dashboard Stripe, kirim pelanggan ke Stripe Checkout dalam mode langganan, tangani event langganan dengan webhook, dan tautkan tombol Kelola tagihan ke portal pelanggan Stripe yang dihosting. Dengan begitu kamu tidak perlu membangun formulir kartu dan layar perubahan paket sendiri.
Event webhook Stripe apa saja yang saya butuhkan untuk langganan?
Minimal checkout.session.completed untuk menautkan langganan baru ke pengguna kamu, invoice.paid untuk memastikan setiap pembayaran berhasil, invoice.payment_failed untuk memberi peringatan tentang perpanjangan yang gagal, serta customer.subscription.updated dan customer.subscription.deleted untuk melacak perubahan paket dan pembatalan.
Apa yang terjadi saat pembayaran langganan gagal?
Menurut dokumentasi Stripe per September 2026, langganan biasanya berubah menjadi past_due dan Stripe bisa mencoba ulang pembayaran sesuai pengaturanmu. Setelah percobaan terakhir, pengaturan Dashboard kamu menentukan apakah langganan dibatalkan, ditandai unpaid, atau dibiarkan past_due.
Bisakah saya menawarkan uji coba gratis tanpa meminta kartu?
Bisa. Stripe mendukung uji coba gratis, dan dokumentasinya menjelaskan status paused untuk uji coba yang berakhir tanpa metode pembayaran jika diatur demikian. Meminta kartu di awal biasanya berarti lebih sedikit pendaftar tetapi lebih banyak pelanggan berbayar; uji mana yang paling cocok untuk produkmu.