Stripe — jak działa: integracje

Stripe API pozwala programistom połączyć aplikację z funkcjami płatniczymi Stripe.¹ W artykule opisujemy przebieg płatności, integrację z WooCommerce, PrestaShop i Shopify oraz pracę bezpośrednio z API. Omawiamy też obsługę w panelu, zwroty i typowe błędy.
Payment Element pozwala udostępnić klientom ponad 100 metod płatności².

Stripe API jako podstawa integracji płatności

Stripe API to interfejs, przez który aplikacja wymienia dane ze Stripe podczas obsługi płatności. Programista decyduje, kiedy wysłać żądanie i jak wykorzystać odpowiedź.
Globalny limit API wynosi 100 żądań na sekundę w trybie produkcyjnym i 25 w środowisku testowym³.

Referencja API opisuje dostępne żądania, pola i odpowiedzi. Dzięki niej programista ustala, jakie dane przekazać do Stripe, a jakie zapisać we własnym systemie. Przy jednym obiekcie Stripe można zapisać maksymalnie 50 kluczy metadanych⁴.

Czym jest Stripe API?

Stripe API określa, jak aplikacja komunikuje się ze Stripe za pomocą żądań i odpowiedzi. Referencja podaje nazwy pól oraz ograniczenia ich wartości.
Pole amount obiektu PaymentIntent przyjmuje wartość o maksymalnie ośmiu cyfrach, wyrażoną w najmniejszej jednostce waluty⁵.

lookup_key obiektu Feature to identyfikator nadawany we własnym systemie. Może mieć maksymalnie 80 znaków.⁶ Aplikacja musi uwzględnić ten limit już przy tworzeniu identyfikatora.

Integracja musi respektować dopuszczalne wartości pól opisane w Stripe API. Dotyczy to także metadanych: nazwa ich klucza może mieć maksymalnie 40 znaków⁴.

Jakie obiekty Stripe API opisują płatności i zwroty?

PaymentIntent pozwala aplikacji śledzić stan płatności, a Refund wiąże zwrot z wcześniejszą płatnością. Metoda płatności, na przykład karta, wskazuje sposób zapłaty klienta, nie wynik transakcji.
Aplikacja może śledzić siedem możliwych statusów obiektu PaymentIntent⁵.

Metody płatności klienta można pobrać w PHP przez wywołanie paymentMethods->all(). Przykład przekazuje identyfikator klienta w parametrze customer oraz wartość card w parametrze type.⁷ Parametr customer wskazuje klienta, a type ogranicza wynik do kart⁸.

Secret jest osobnym obiektem Stripe API. Ma identyfikator id, nazwę name unikalną w swoim zakresie oraz pole payload z wartością sekretu zapisaną jako jawny tekst.⁹ Secret nie opisuje płatności ani zwrotu. Pola payload nie należy więc traktować jak statusu transakcji.

Przy obsłudze zwrotu trzeba powiązać Refund z właściwą płatnością. Jeśli zwrotów częściowych jest kilka, ich łączna kwota nie może przekroczyć pierwotnej kwoty obciążenia¹⁰.

Jak wersja API wpływa na integrację?

Wersja Stripe API wpływa na interpretację żądań i odpowiedzi. Przed zmianą sprawdź, czy kod nadal odpowiada używanym polom i formatowi danych.
Przykładowy identyfikator wersji w nagłówku Stripe-Version to 2026-09-30.endive: zawiera datę oraz nazwę wydania¹¹.

Najpierw ustal wersję używaną przez aplikację i bibliotekę serwerową. Zapisz ją w konfiguracji wdrożenia, żeby zmiana środowiska nie zmieniła po cichu zachowania kodu.
W żądaniu z nagłówkiem Stripe-Version wskazana wersja zastępuje domyślną wersję API konta¹¹.

Kod obsługi odpowiedzi porównaj z opisem docelowej wersji API. Sprawdź nazwy i typy pól, zwłaszcza tam, gdzie aplikacja odczytuje status płatności lub zwrotu. Pole status obiektu Refund może przyjmować pięć wartości: pending, requires_action, succeeded, failed lub canceled¹².

Zmianę wersji przetestuj przed wdrożeniem w środowisku testowym. Utwórz płatność, odczytaj jej wynik i obsłuż zwrot; wykryte różnice uwzględnij w kodzie. Udany scenariusz płatności można sprawdzić w formularzu testowym kartą o numerze 4242 4242 4242 4242¹³.

W żądaniach używaj wersji, dla której sprawdzono kod obsługujący odpowiedzi. Inaczej nawet poprawnie wysłane żądanie może wymagać zmian po stronie aplikacji. Podobnie integracja przez imoje API wymaga, by aplikacja poprawnie obsługiwała odpowiedzi dotyczące transakcji i zwrotów.

Jak uwierzytelnić żądania kluczem Stripe API?

Klucz Stripe API uwierzytelnia żądania wysyłane przez aplikację. Klucz publiczny zaczyna się od pk_test_ i może trafić do przeglądarki. Tajny klucz sk_test_ należy przechowywać na serwerze¹⁴.

Panel Stripe pozwala pobrać klucz dla środowiska testowego albo produkcyjnego. Tajny klucz zapisz w konfiguracji serwera, poza kodem publikowanym w repozytorium.
Nie powinien pojawić się także w kodzie dostępnym w przeglądarce.

Żądanie HTTPS do Stripe API przekazuje tajny klucz w nagłówku Authorization jako token Bearer. Biblioteka Stripe może ustawić ten nagłówek, gdy otrzyma klucz z konfiguracji aplikacji. Za bezpieczne przechowywanie klucza nadal odpowiada programista.

Odpowiedź API pozwala odróżnić błąd uwierzytelnienia od błędu danych żądania. Gdy zawodzi uwierzytelnienie, sprawdź użyty klucz oraz środowisko. Aplikacja nie powinna mieszać kluczy testowych z produkcyjnymi.

Do poprawnego uwierzytelnienia potrzebny jest tajny klucz po stronie serwera. Klucz musi też odpowiadać środowisku, do którego aplikacja wysyła żądanie¹⁵.

Jak odbierać zdarzenia przez Stripe webhooks?

Stripe webhooks przekazują aplikacji powiadomienia o zdarzeniach płatniczych. Przygotuj serwerowy adres HTTPS i zarejestruj go w Stripe jako punkt odbioru zdarzeń. Dzięki temu aplikacja może reagować na zmiany statusu płatności.

Punkt odbioru webhooków powinien przyjmować żądania POST. Musi też zachować niezmienioną treść żądania, ponieważ jest ona potrzebna do weryfikacji podpisu. Skonfiguruj tylko te typy zdarzeń, które aplikacja potrafi obsłużyć.

Sekret podpisu webhooka pozwala potwierdzić, że zdarzenie pochodzi ze Stripe. Zweryfikuj podpis, zanim odczytasz dane zdarzenia.
Sekret trzymaj w konfiguracji serwera, oddzielnie od klucza API.

Obsługa zdarzenia powinna zacząć się od odczytania jego typu i identyfikatora. Potem aplikacja wykonuje właściwą operację, na przykład aktualizuje status zamówienia. Zapisz identyfikator przetworzonego zdarzenia, aby ponowne dostarczenie nie powtórzyło operacji. Po poprawnym przetworzeniu zwróć odpowiedź potwierdzającą odbiór¹⁶.

Aktualizację zamówienia opieraj na zweryfikowanym zdarzeniu Stripe. Sprawdzenie podpisu chroni przed nieuprawnioną operacją, a zapis identyfikatora zdarzenia – przed jej powtórzeniem.

Jak testować płatności i diagnozować błędy bez prawdziwych transakcji?

Stripe pozwala prześledzić płatność w środowisku testowym. Diagnozę błędu zacznij od konkretnego żądania: ustal, które się nie powiodło i jaką odpowiedź zwróciło API.

Środowisko testowe ustaw w konfiguracji aplikacji i użyj przypisanych do niego kluczy. Przeprowadź płatność testową, po czym porównaj status w aplikacji ze statusem w panelu Stripe.
Globalny limit API w tym środowisku wynosi 25 żądań na sekundę.

Karty testowe Stripe, wyszukiwane także jako „testcard Stripe”, pozwalają odtwarzać scenariusze bez obciążania rzeczywistej karty. Stripe CLI może przekazać testowe zdarzenia webhook do lokalnej aplikacji. W ten sposób sprawdzisz jej reakcję na zmianę statusu.

Błąd „Missing required param: customer” przy wywołaniu paymentMethods->all() oznacza brak parametru customer w opisanym przykładzie integracji Stripe API z PHP.⁷ Dodaj do żądania identyfikator właściwego klienta. Następnie ponów test.

Porównaj testowe żądanie, odpowiedź API i status w panelu Stripe. Takie zestawienie pomaga ustalić, czy problem leży w parametrach, czy w obsłudze płatności przez aplikację.

Checkout czy własny formularz: co wybrać do sklepu?

Stripe Checkout kieruje klienta na stronę płatności obsługiwaną przez Stripe. Własny formularz płatności pozostaje na stronie sklepu.
Wybór zależy od dostępnego czasu na prace programistyczne i potrzebnej kontroli nad interfejsem.

Tabela porównuje Checkout i własny formularz pod kątem miejsca płatności, prac wdrożeniowych oraz kontroli nad interfejsem.

Odpowiedzialność za interfejs stanowi główną różnicę. Checkout przenosi stronę płatności do Stripe, a własny formularz wymaga utrzymania jej w sklepie.
Własny formularz nie oznacza jednak, że sklep musi przechowywać dane karty. Pola płatnicze należy wdrażać przy użyciu narzędzi Stripe przeznaczonych do bezpiecznego zbierania tych danych.

Stripe Checkout pasuje do sklepu, który chce ograniczyć prace nad interfejsem płatności, ale nie do sklepu potrzebującego pełnej kontroli nad układem.

Własny formularz pasuje do sklepu, który chce przyjmować płatność na swojej stronie, ale nie do zespołu unikającego utrzymania dodatkowego kodu interfejsu.

Czym różni się bezpośrednie wywołanie API od użycia Stripe SDK?

Bezpośrednie wywołanie Stripe API wymaga przygotowania żądania HTTP i odczytania odpowiedzi. Stripe SDK udostępnia do tych czynności metody w języku aplikacji.
Oba rozwiązania komunikują się z API; różni je ilość kodu komunikacyjnego, który utrzymuje programista.

Tabela porównuje bezpośrednie wywołanie API i Stripe SDK pod kątem wysyłania żądań, obsługi odpowiedzi, zależności projektu oraz limitów.

StripeClient to klasa klienta używana w integracji PHP. W podanym przykładzie klienta Stripe można wyszukać przez customers->search() albo utworzyć przez customers->create().⁷ SDK zastępuje ręczne składanie żądań. Aplikacja nadal musi jednak zdecydować, kiedy wyszukać klienta, a kiedy go utworzyć.

Stripe SDK pasuje do projektu, który chce ograniczyć własny kod komunikacji z API, ale nie do projektu unikającego zależności od biblioteki.

Bezpośrednie wywołanie API pasuje do projektu wymagającego kontroli nad żądaniami HTTP, ale nie do zespołu, który nie chce utrzymywać ich obsługi.

Ceny i warunki sprawdzone u źródeł: październik 2026.