Jak dodać subskrypcje w Stripe: plany, okresy próbne, webhooki i nieudane płatności
Aby dodać subskrypcje w Stripe, utwórz w panelu Stripe produkt z ceną cykliczną, wysyłaj klientów z serwera do Stripe Checkout w trybie subskrypcji, a webhook niech informuje aplikację, kiedy każda płatność się udaje, nie udaje, zmienia się lub kończy. Zapisuj status subskrypcji przy użytkowniku i na tej podstawie przyznawaj dostęp, a nie na podstawie strony sukcesu. Dodaj przycisk Zarządzaj płatnościami, który otwiera hostowany przez Stripe portal klienta, aby ludzie mogli zmieniać karty, przełączać plany i anulować bez budowania tych ekranów przez Ciebie.
Ten poradnik opiera się na jak dodać płatności do aplikacji, który omawia jednorazowy Checkout, tryb testowy i uruchomienie produkcyjne. Tutaj skupiamy się na tym, co jest inne przy płatnościach cyklicznych. Szczegóły Stripe pochodzą z dokumentacji Stripe według stanu na wrzesień 2026.
Dlaczego subskrypcje są trudniejsze niż jednorazowe płatności
Jednorazowa płatność dzieje się, gdy klient jest w Twojej aplikacji. Subskrypcja trwa dalej po jego odejściu: odnowienia co miesiąc, karty, które wygasają, zmiany planu w trakcie cyklu, anulowania działające od końca okresu rozliczeniowego. Twoja aplikacja dowiaduje się o tym tylko przez webhooki. Większość błędów przy subskrypcjach bierze się z traktowania pierwszej płatności jako całej historii.
Twoje opcje
| Podejście | Co budujesz | Najlepsze do |
|---|---|---|
| Payment Link z ceną cykliczną | Nic poza linkiem | Testowania popytu; ręcznego nadawania dostępu |
| Checkout (tryb subskrypcji) + portal klienta | Trasę serwerową, webhook, przycisk rozliczeń | Większości aplikacji SaaS i członkostw |
| API subskrypcji z własnym formularzem płatności | Znacznie więcej: interfejs płatności, uwierzytelnianie, ponowienia | Aplikacje z nietypowymi przepływami rozliczeń |
| Dostawca typu merchant of record | Podobnie jak Checkout | Sprzedawców, którzy chcą, by dostawca obsługiwał podatek od sprzedaży |
Dla większości aplikacji Checkout plus portal to właściwy kompromis. Jeśli obsługa podatków Cię martwi, porównaj dostawców w artykule Stripe vs Paddle vs Lemon Squeezy.
Najpierw zaplanuj ceny w Stripe
W Stripe produkt to to, co sprzedajesz („Pro plan”), a cena to sposób, w jaki za niego pobierasz opłatę („20 $ miesięcznie”, „200 $ rocznie”). Jeden produkt może mieć kilka cen. Ustal:
- Jakie poziomy oferujesz i co każdy odblokowuje w aplikacji
- Miesięcznie, rocznie, czy oba warianty
- Czy oferujesz okres próbny i czy wymaga on karty z góry
Utwórz produkty i ceny w trybie testowym i zapisz ich ID cen; Twoja aplikacja będzie się do nich odwoływać. Jeśli nie ustaliłeś cennika, przeczytaj jak wycenić produkt SaaS oraz freemium kontra bezpłatny okres próbny.
Cykl życia subskrypcji, który musisz obsłużyć
Przegląd subskrypcji w Stripe wymienia statusy, jakie może mieć subskrypcja. Najważniejsze dla dostępu to:
| Status | Co oznacza | Przyznać dostęp? |
|---|---|---|
trialing | Trwa okres próbny | Tak |
active | Wszystko w porządku | Tak |
incomplete | Pierwsza płatność jeszcze nie została zrealizowana; Stripe daje klientowi 23 godziny | Nie |
incomplete_expired | Pierwsza płatność nigdy się nie powiodła | Nie |
past_due | Ostatnia płatność się nie udała lub nie została podjęta; mogą nastąpić ponowienia | Decyzja należy do Ciebie; wiele aplikacji daje krótki okres karencji |
unpaid | Ponowienia się zakończyły, faktury pozostają otwarte, bez dalszych prób | Nie; dokumentacja Stripe zaleca odebranie dostępu |
canceled | Zakończona; nie da się jej wznowić | Nie |
paused | Okres próbny zakończył się bez metody płatności i został wstrzymany | Nie |
Zapisz status przy rekordzie użytkownika lub konta i na nim opieraj dostęp. Aktualizuj go za każdym razem, gdy nadejdzie odpowiedni webhook.
Zdarzenia webhooków do obsłużenia
| Zdarzenie | Co robi Twoja aplikacja |
|---|---|
checkout.session.completed | Powiąż ID nowego klienta i subskrypcji Stripe z użytkownikiem |
invoice.paid | Oznacz subskrypcję jako aktywną i zapisz koniec nowego okresu |
invoice.payment_failed | Poinformuj użytkownika, że karta została odrzucona, i podaj link do portalu |
invoice.payment_action_required | Poproś użytkownika o dokończenie uwierzytelniania karty |
customer.subscription.updated | Zaktualizuj plan, status i ewentualne zaplanowane anulowanie |
customer.subscription.deleted | Usuń dostęp płatny |
customer.subscription.trial_will_end | Przypomnij użytkownikowi przed końcem okresu próbnego; Stripe wysyła to na trzy dni przed |
Zasady obsługi z dokumentacji webhooków Stripe nadal obowiązują: weryfikuj podpis na surowym ciele żądania, szybko zwracaj odpowiedź 2xx, obsługuj duplikaty i zdarzenia w złej kolejności oraz spodziewaj się ponowień. Idea webhooka jest wyjaśniona w poradniku czym jest webhook, a szczegółowe zasady są w poradniku o płatnościach.
Krok po kroku
- Utwórz produkty i ceny w trybie testowym Stripe.
- Dodaj sekrety: klucz tajny, ID cen, a później klucz podpisujący webhooka. Nigdy nie umieszczaj ich w kodzie frontendu.
- Strona z cennikiem: przycisk każdego planu wywołuje Twój serwer, który tworzy sesję Checkout w trybie subskrypcji dla zalogowanego użytkownika. Przekaż ID użytkownika, aby webhook mógł dopasować płatność do konta.
- Endpoint webhooka: weryfikuj podpisy i obsługuj powyższe zdarzenia, aktualizując jeden rekord subskrypcji na użytkownika.
- Ogranicz funkcje na podstawie zapisanego statusu i planu, sprawdzanych na serwerze przy każdym chronionym działaniu, a nie tylko przez ukryte przyciski.
- Portal klienta: skonfiguruj go w panelu Stripe (na jakie plany można przejść, czy można anulować), a potem dodaj przycisk Zarządzaj płatnościami, który tworzy na serwerze sesję portalu i przekierowuje do niego.
- Nieudane płatności: w ustawieniach rozliczeń Stripe wybierz zachowanie ponowień i to, co się dzieje po ostatniej próbie. Pokazuj w aplikacji baner, gdy status to
past_due. - Przetestuj cały cykl życia, potem opublikuj i zarejestruj produkcyjny webhook.
Prompty dla asystenta do budowania
Dodaj rozliczanie subskrypcji przez Stripe. Plany: Starter (ID ceny w STRIPE_PRICE_STARTER) i Pro (STRIPE_PRICE_PRO). Strona z cennikiem tworzy na serwerze sesję Checkout w trybie subskrypcji, używając STRIPE_SECRET_KEY, z dołączonym ID zalogowanego użytkownika. Zapisz przy użytkowniku ID klienta Stripe, ID subskrypcji, plan i status. Nigdy nie udostępniaj klucza tajnego przeglądarce.
Dodaj POST /api/stripe/webhook. Weryfikuj podpis kluczem STRIPE_WEBHOOK_SECRET na surowym ciele żądania. Obsłuż checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted i customer.subscription.trial_will_end. Zapisuj ID przetworzonych zdarzeń, aby duplikaty były ignorowane. Aktualizuj status użytkownika na podstawie obiektu subskrypcji, a nie kolejności, w jakiej przychodzą zdarzenia.
Ogranicz funkcje Pro po stronie serwera: udostępniaj je tylko wtedy, gdy status to active lub trialing, a plan to Pro. Gdy status to past_due, pokaż baner „Płatność nie powiodła się, zaktualizuj kartę”. Dodaj przycisk Zarządzaj płatnościami, który otwiera portal klienta Stripe dla tego użytkownika.
Ulepszenia, obniżki i proporcjonalne rozliczenie
Gdy klient przełącza plan, według dokumentacji Stripe zmiana często tworzy proporcjonalne rozliczenie (proration): nowa cena jest naliczana za pozostałą część bieżącego okresu rozliczeniowego. Możesz podejrzeć takie wyliczenia albo je wyłączyć. Jeśli plany mają ten sam interwał, daty rozliczeń pozostają takie same; przejście z miesięcznego na roczny przesuwa datę rozliczenia na dzień zmiany. Pozwolenie klientom na zmianę planu w portalu oszczędza pisania tej logiki, ale w ustawieniach portalu zdecyduj, jakie zmiany są dozwolone.
Lista kontrolna testów
Używaj trybu testowego Stripe i kart testowych, i przejdź przez każdy stan:
- Nowa subskrypcja przyznaje właściwy plan właściwemu użytkownikowi
- Zamknięcie karty zaraz po zapłacie nadal przyznaje dostęp (dowodzi to, że webhook działa)
- Odrzucona karta przy rejestracji nie przyznaje niczego
- Nieudane odnowienie przenosi konto do past_due i pokazuje baner
- Aktualizacja karty w portalu przywraca status active
- Ulepszenie i obniżenie planu poprawnie zmieniają funkcje
- Anulowanie na koniec okresu zachowuje dostęp do daty końcowej, a potem go usuwa
- Użytkownicy w okresie próbnym mają dostęp, dostają przypomnienie i poprawnie przechodzą na płatność lub tracą dostęp
- Wysłanie tego samego zdarzenia webhooka dwa razy niczego nie zmienia
Zegary testowe Stripe pozwalają symulować upływ czasu, więc możesz testować odnowienia bez czekania miesiąc. Aktualną instrukcję ich użycia znajdziesz w bieżącej dokumentacji testowania Stripe.
Częste błędy
- Przyznawanie dostępu na stronie sukcesu. Klienci mogą zapłacić i nigdy na nią nie trafić. Użyj webhooka.
- Obsługa tylko pierwszej płatności. Odnowienia, nieudane płatności i anulowania przychodzą później jako zdarzenia.
- Sprawdzanie statusu planu tylko w frontendzie. Każdy może wywołać Twoje API bezpośrednio.
- Przypadkowo wiele subskrypcji jednego użytkownika. Sprawdź istniejącą subskrypcję przed utworzeniem nowej sesji Checkout albo kieruj istniejących klientów do portalu.
- Odbieranie dostępu przy pierwszej nieudanej odnowie. Karty zawodzą z nudnych powodów. Krótki okres karencji z wyraźnym banerem zatrzymuje klientów.
- Zapomniany produkcyjny webhook. Endpointy testowy i produkcyjny mają różne klucze podpisujące.
- Ignorowanie podatków i zwrotów. Przed startem ustal politykę zwrotów i sprawdź obowiązki podatkowe u księgowego.
Subskrypcje w Mythex
Aplikacje budowane w Mythex korzystają z Twojego własnego konta i kluczy Stripe; nie ma połączenia Stripe w jednym kliknięciu dla Twojej aplikacji. Dodaj klucze testowe i ID cen jako sekrety projektu, używaj promptów podobnych do powyższych i testuj testowymi kartami Stripe w podglądzie. Webhooki potrzebują publicznego adresu Twojej aplikacji, więc opublikuj ją przed zarejestrowaniem endpointu w Stripe, i opublikuj ponownie po przełączeniu na klucze produkcyjne, aby aplikacja na żywo je podchwyciła. Zobacz Przyjmowanie płatności przez Stripe oraz Obsługa webhooków w backendzie. Szerszy kontekst produktu, czyli co zbudować wokół rozliczeń, opisuje poradnik jak zbudować MVP SaaS.
Pytania
Jaki jest najprostszy sposób na dodanie subskrypcji w Stripe?
Utwórz produkt z ceną cykliczną w panelu Stripe, wysyłaj klientów do Stripe Checkout w trybie subskrypcji, obsługuj zdarzenia subskrypcji przez webhook i połącz przycisk „Zarządzaj płatnościami” z hostowanym przez Stripe portalem klienta. Dzięki temu nie musisz sam budować formularzy kart ani ekranów zmiany planu.
Jakich zdarzeń webhooka Stripe potrzebuję dla subskrypcji?
Co najmniej checkout.session.completed, aby powiązać nową subskrypcję z użytkownikiem, invoice.paid, aby potwierdzać każdą udaną płatność, invoice.payment_failed, aby ostrzegać o nieudanych odnowieniach, oraz customer.subscription.updated i customer.subscription.deleted, aby śledzić zmiany planów i anulowania.
Co się dzieje, gdy płatność za subskrypcję się nie uda?
Według dokumentacji Stripe, stan na wrzesień 2026, subskrypcja zwykle przechodzi w stan past_due, a Stripe może ponowić płatność zgodnie z Twoimi ustawieniami. Po ostatniej próbie ustawienia w panelu decydują, czy subskrypcja zostanie anulowana, oznaczona jako nieopłacona, czy pozostanie past_due.
Czy mogę zaoferować bezpłatny okres próbny bez pytania o kartę?
Tak. Stripe obsługuje bezpłatne okresy próbne, a jego dokumentacja opisuje status paused dla okresów próbnych, które kończą się bez metody płatności, jeśli tak to skonfigurujesz. Pobieranie karty z góry zwykle oznacza mniej rejestracji, ale więcej płacących klientów; sprawdź, co pasuje do Twojego produktu.