Jak dodać płatności do aplikacji: checkout, subskrypcje i webhooki

Najprostszym sposobem na dodanie płatności do aplikacji jest Stripe: użyj Payment Link, jeśli potrzebujesz tylko przycisku „Kup” i możesz obsługiwać zamówienia ręcznie, Stripe Checkout, jeśli aplikacja ma wiedzieć, kto zapłacił, i automatycznie na to reagować, oraz Checkout w trybie subskrypcji wraz z portalem klienta Stripe przy płatnościach cyklicznych. We wszystkich przypadkach poza najprostszym potrzebujesz też webhooka — endpointu na serwerze, który Stripe wywołuje po udanej płatności — i powinieneś przetestować wszystko kluczami testowymi oraz testowymi kartami, zanim przełączysz się na klucze produkcyjne.

Ten poradnik wyjaśnia każdą opcję, część z webhookami, którą pomija większość tutoriali, i to, co sprawdzić przed przyjęciem prawdziwych pieniędzy. Szczegóły Stripe pochodzą z jego własnej dokumentacji według stanu na wrzesień 2026.

Po co w ogóle korzystać z dostawcy płatności

Nigdy nie zbieraj numerów kart we własnych formularzach. Obsługa surowych danych kart wciąga Cię w zakres PCI DSS (standardu bezpieczeństwa branży kartowej) i stanowi poważne ryzyko. Dostawca płatności, taki jak Stripe, hostuje formularz płatności, przechowuje kartę, obsługuje uwierzytelnianie w banku i przekazuje Twojej aplikacji wynik. Aplikacja widzi tylko: „klient X zapłacił za Y”.

Ten poradnik używa Stripe, bo jest szeroko stosowany, dobrze udokumentowany i wspierany przez większość asystentów do budowania aplikacji. Istnieją inni dostawcy, a niektórzy działają jako „merchant of record” i przejmują za Ciebie obsługę podatku od sprzedaży; jeśli zgodność podatkowa Cię martwi, ten model warto porównać.

Trzy sposoby przyjmowania płatności przez Stripe

Payment Links

Payment Link to strona płatności hostowana przez Stripe, którą tworzysz w panelu Stripe bez kodu. Dostajesz adres URL, który możesz umieścić za przyciskiem w aplikacji, udostępnić w e-mailu lub pokazać jako kod QR. Dokumentacja Stripe mówi, że Payment Links mogą sprzedawać produkt, subskrypcję albo przyjmować darowiznę, a klienci mogą sami wybrać, co zapłacić, lub liczba zakupów może być ograniczona.

Haczyk: Twoja aplikacja nie wie automatycznie, że konkretny zalogowany użytkownik zapłacił. Przy stronie darowizn albo małym sklepie, w którym zamówienia realizujesz ręcznie na podstawie powiadomień e-mail ze Stripe, to wystarcza. Przy „zapłać, by odblokować funkcje Pro” już nie.

Stripe Checkout

Checkout to strona płatności, którą Twój serwer tworzy na żądanie dla konkretnego zakupu. Serwer mówi Stripe, co jest kupowane (i opcjonalnie, który klient kupuje), Stripe zwraca adres URL, a Ty wysyłasz tam klienta. Według dokumentacji Stripe Checkout obsługuje zarówno płatności jednorazowe, jak i subskrypcje, i może być pełną stroną hostowaną przez Stripe, stroną osadzoną w Twojej witrynie albo osadzonym formularzem.

Przebieg:

1. Klient klika Kup w Twojej aplikacji.
2. Twój serwer tworzy sesję Checkout przy użyciu klucza tajnego, z identyfikatorem łączącym ją z użytkownikiem lub zamówieniem.
3. Klient zostaje przekierowany do Stripe i płaci.
4. Stripe przekierowuje go z powrotem na Twoją stronę sukcesu.
5. Stripe wysyła zdarzenie checkout.session.completed do Twojego webhooka, a serwer oznacza zamówienie jako opłacone lub odblokowuje dostęp.

Krok 2 musi odbyć się na serwerze, bo używa Twojego klucza tajnego. To główny powód, dla którego Checkout wymaga backendu.

Subskrypcje

Subskrypcje korzystają z Checkout w trybie subskrypcji z cykliczną ceną skonfigurowaną w Stripe. Pierwsza płatność działa jak opisany wyżej przepływ. Później odnowienia, nieudane płatności kartą, zmiany planu i anulowania następują w czasie — często wtedy, gdy klienta w ogóle nie ma w aplikacji — więc aplikacja dowiaduje się o nich wyłącznie przez webhooki.

Aby klient mógł sam zarządzać subskrypcją, Stripe oferuje hostowany portal klienta. Według dokumentacji Stripe klienci mogą tam aktualizować metody płatności i dane do rozliczeń, zmieniać lub anulować subskrypcje, a także przeglądać i pobierać faktury. Konfigurujesz go w panelu Stripe i dodajesz przycisk „Zarządzaj płatnościami”, który wysyła klienta do portalu. Dzięki temu nie musisz samodzielnie budować tych ekranów.

Webhooki: część, której nie można pominąć

Webhook to żądanie HTTP, które Stripe wysyła na Twój serwer, gdy coś się wydarzy. (Ogólne wyjaśnienie znajdziesz w artykule czym jest webhook.) Przewodnik Stripe po realizacji zamówień jest jednoznaczny: nie można polegać wyłącznie na stronie sukcesu, bo klient może zapłacić, a potem stracić połączenie, zanim strona się wczyta. Przy subskrypcjach i opóźnionych metodach płatności webhooki są wymagane.

Zdarzenia, które warto obsłużyć

Zasady poprawnej obsługi webhooka

Pochodzą one wprost z dokumentacji webhooków Stripe, a wygenerowane przez AI handlery czasem pomijają któryś punkt:

• Weryfikuj podpis. Każde zdarzenie zawiera nagłówek Stripe-Signature. Handler sprawdza go kluczem podpisującym endpointu (zaczyna się od whsec_). Bez tego ktokolwiek mógłby wysłać na Twój serwer fałszywe „płatność udana”.
• Używaj surowego ciała żądania. Sprawdzanie podpisu nie działa, jeśli framework najpierw sparsuje lub zmodyfikuje treść.
• Szybko zwracaj odpowiedź 2xx, a wolniejsze prace wykonuj potem. Przekroczenie czasu liczy się jako błąd.
• Obsługuj duplikaty. Stripe może dostarczyć to samo zdarzenie więcej niż raz. Zapisuj ID przetworzonych zdarzeń albo zrób realizację tak, by bezpiecznie dało się ją uruchomić dwa razy.
• Nie zakładaj kolejności. Stripe nie gwarantuje, że zdarzenia dotrą w kolejności, w jakiej się wydarzyły.
• Spodziewaj się ponowień. W trybie produkcyjnym Stripe ponawia nieudane dostarczenia przez do trzech dni, więc krótka awaria nie zgubi płatności — ale handler musi radzić sobie ze spóźnionymi zdarzeniami.

Webhooki potrzebują publicznego adresu HTTPS, więc zwykle działają dopiero po opublikowaniu aplikacji (CLI Stripe może przekazywać zdarzenia na komputer dewelopera).

Prompt obejmujący cały przepływ

Dodaj jednorazowy zakup przez Stripe Checkout dla „Pro pack” (ID ceny w STRIPE_PRICE_ID). Utwórz sesję Checkout po stronie serwera, używając STRIPE_SECRET_KEY z sekretów, i dołącz do sesji ID zalogowanego użytkownika. Dodaj endpoint POST /api/stripe/webhook, który weryfikuje podpis Stripe kluczem STRIPE_WEBHOOK_SECRET na surowym ciele żądania, obsługuje checkout.session.completed i oznacza tego użytkownika jako posiadającego Pro pack. Niech będzie bezpieczny, gdy to samo zdarzenie przyjdzie dwa razy. Dodaj strony sukcesu i anulowania. Nigdy nie udostępniaj klucza tajnego przeglądarce.

Dla subskrypcji dodaj: „Użyj trybu subskrypcji z STRIPE_PRICE_ID. Obsłuż invoice.paid, invoice.payment_failed, customer.subscription.updated i customer.subscription.deleted. Dodaj przycisk Zarządzaj płatnościami, który otwiera portal klienta Stripe.”

Tryb testowy

Stripe ma osobne środowiska sandbox (testowe) i produkcyjne, z oddzielnymi kluczami. Klucze testowe zaczynają się od pk_test_, sk_test_ lub rk_test_; produkcyjne od pk_live_, sk_live_ lub rk_live_. Transakcje testowe nie przenoszą pieniędzy.

Przydatne karty testowe z dokumentacji testowania Stripe (dowolna przyszła data ważności, dowolne trzycyfrowe CVC):

Przetestuj co najmniej:

• Udana płatność odblokowuje właściwą rzecz dla właściwego użytkownika
• Odrzucona karta pokazuje jasny komunikat i nic nie odblokowuje
• Zamknięcie karty przeglądarki zaraz po zapłacie nadal skutkuje dostępem (to dowodzi, że działa webhook, a nie tylko strona sukcesu)
• Anulowanie na stronie Stripe wraca użytkownika do aplikacji bez obciążenia
• Przy subskrypcjach: anuluj w portalu klienta i sprawdź, że dostęp kończy się, kiedy powinien

Uruchomienie produkcyjne

1. Aktywuj konto Stripe danymi firmy i bankowymi.
2. Podmień klucze na produkcyjne w sekretach aplikacji. Stripe zaleca klucze ograniczone, z uprawnieniami tylko tymi, których potrzebuje integracja, zamiast nieograniczonego klucza tajnego.
3. Utwórz produkcyjny endpoint webhooka wskazujący na opublikowaną aplikację. Ma on własny klucz podpisujący, inny niż testowy — zaktualizuj go.
4. Odtwórz produkty i ceny w trybie produkcyjnym; ID z trybu testowego tam nie istnieją.
5. Wykonaj jeden prawdziwy, mały zakup i go zwróć.

Każdy klucz trzymaj w sekretach projektu, nigdy w kodzie ani w czacie. Nasza lista kontrolna bezpieczeństwa szerzej omawia klucze i weryfikację webhooków.

Podatki, zwroty i formalności

Płatności wiążą się z obowiązkami, których kod nie rozwiąże. To nie jest porada podatkowa; skonsultuj się z księgowym.

• Podatek od sprzedaży, VAT i GST. W zależności od tego, gdzie Ty i Twoi klienci się znajdujecie, może być konieczna rejestracja, pobieranie i rozliczanie podatku. Stripe Tax potrafi obliczyć i pobrać podatek przy płatności, monitorować, gdzie Twoja sprzedaż może rodzić obowiązek, i pomóc w rejestracjach oraz rozliczeniach — ale odpowiedzialność pozostaje po Twojej stronie. Alternatywą są dostawcy typu merchant of record, którzy przejmują więcej tych obowiązków.
• Zwroty i spory. Ustal politykę zwrotów przed startem i umieść ją na stronie. Spory (chargebacki) się zdarzają; prowadź zapisy tego, co zostało kupione i dostarczone.
• Paragony i faktury. Stripe może wysyłać paragony e-mailem; firmy mogą potrzebować pełnoprawnych faktur.
• Opłaty. Każdy dostawca pobiera opłatę za transakcję. Sprawdź aktualny cennik dostawcy, zamiast polegać na liczbach z artykułów.

Która konfiguracja pasuje do Twojej aplikacji

• Darowizny lub kilka produktów: Payment Links. Zobacz jak zbudować stronę do darowizn dla organizacji non-profit.
• Sklep z koszykiem: Checkout z pozycjami i webhookiem. Zobacz jak zbudować sklep internetowy.
• SaaS lub członkostwa: Checkout w trybie subskrypcji, webhooki i portal klienta. Zobacz jak zbudować MVP SaaS oraz jak wycenić produkt SaaS.
• Marketplace wypłacający sprzedawcom: inna, bardziej uregulowana konfiguracja (Stripe Connect lub podobna). Zaplanuj ją osobno.

Dodawanie płatności w Mythex

Płatności w aplikacjach budowanych w Mythex korzystają z Twojego własnego konta Stripe i kluczy; nie ma przycisku „Połącz Stripe” dla Twojej aplikacji. Typowy przebieg:

1. Zdobądź klucze testowe Stripe.
2. Dodaj STRIPE_SECRET_KEY (a później sekret webhooka) do sekretów projektu — przez /secrets, ustawienia projektu lub kartę sekretów, którą agent pokazuje, gdy potrzebuje klucza.
3. Poproś agenta o Checkout, używając promptu podobnego do powyższego.
4. Testuj w podglądzie testowymi kartami. Opublikuj aplikację przed rejestracją webhooka, bo potrzebuje on Twojego publicznego adresu.
5. Po przełączeniu na klucze produkcyjne opublikuj ponownie, aby aplikacja na żywo je podchwyciła.

Zobacz w dokumentacji Przyjmowanie płatności przez Stripe oraz Obsługa webhooków w backendzie.

Pytania