Integracja Stripe Przelewy24 sklepu: kompletny przewodnik wdrożeniowy

Integracja Stripe Przelewy24 sklepu to jedna z najczęstszych decyzji technicznych przy uruchamianiu polskiego e-commerce, który chce sprzedawać krajowo i za granicę bez utrzymywania dwóch osobnych bramek. Dobrze zaplanowana integracja Stripe Przelewy24 sklepu pozwala obsłużyć w jednym panelu płatności kartami Visa i Mastercard, portfele Apple Pay oraz Google Pay, a jednocześnie udostępnić klientowi listę kilkudziesięciu banków, do których jest przyzwyczajony. Dla sprzedawcy oznacza to jeden webhook, jeden model danych o transakcjach i jedno miejsce, w którym powstają zwroty. Dla klienta oznacza checkout, w którym nie musi szukać przelewu tradycyjnego. W tym przewodniku pokazuję architekturę takiego rozwiązania, wymagania formalne, konfigurację kluczy API, realne koszty prowizji w PLN oraz błędy, które najczęściej blokują wdrożenie na produkcji. Przykłady opieram na sklepie z peryferiami komputerowymi, bo tam widać zarówno małe koszyki, jak i zamówienia po kilka tysięcy złotych.

Jak działa integracja Stripe Przelewy24 sklepu od strony technicznej

Stripe traktuje Przelewy24 jako lokalną metodę płatności opartą na przekierowaniu. Klient wybiera bank z listy, trafia na stronę pośrednika, autoryzuje przelew i wraca do sklepu z parametrem sesji. Twoja aplikacja nie przechowuje żadnych danych logowania ani numerów kart, co radykalnie upraszcza zakres wymagań PCI DSS i odpowiedzialność techniczną sprzedawcy.

Sercem wdrożenia jest obiekt PaymentIntent. Powstaje w momencie kliknięcia przycisku zapłaty, przechodzi przez status requires_action podczas przekierowania, następnie processing, a finalnie succeeded albo canceled. Status zamówienia w sklepie musi być pochodną tego obiektu, nigdy odwrotnie. To jedyny sposób, aby uniknąć rozjazdu między kasą banku a bazą danych sklepu.

Trzeba też rozumieć ograniczenia tej metody. Przelewy24 w Stripe nie obsługują preautoryzacji ani obciążeń cyklicznych, więc subskrypcje wymagają zapisania karty jako metody rezerwowej. Zwroty są możliwe, ale realizowane asynchronicznie i zwykle trwają od jednego do kilku dni roboczych, co należy jasno opisać w regulaminie oraz w komunikacji potransakcyjnej z klientem.

Kiedy jedna bramka wystarczy, a kiedy potrzebujesz dwóch

Jeśli sprzedajesz wyłącznie w PLN, a średni koszyk nie przekracza kilkuset złotych, jedna bramka w zupełności wystarczy. Sklepy z ofertą premium, takie jak stacje robocze, monitor do komputera klasy referencyjnej czy tablet graficzny wacom dla studiów graficznych, częściej dokładają drugiego operatora jako zabezpieczenie przed awarią i jako źródło alternatywnych rat.

Przygotowanie konta, sklepu i infrastruktury

Zanim dotkniesz kodu, uporządkuj formalności. Konto Stripe wymaga danych rejestrowych firmy, numeru NIP, wpisu do CEIDG lub KRS, dokumentu tożsamości osoby reprezentującej oraz rachunku bankowego prowadzonego w złotych. Weryfikacja zajmuje zwykle od kilku godzin do dwóch dni roboczych, a bez niej wypłaty pozostają zablokowane mimo działającego checkoutu.

Po stronie infrastruktury potrzebujesz stabilnego hostingu z certyfikatem TLS i przewidywalnym czasem odpowiedzi. Popularnym wyborem dla średnich sklepów jest ovh vps z 4 vCPU i 8 GB RAM w cenie kilkudziesięciu złotych miesięcznie. Zbyt wolny serwer wydłuża odpowiedź na webhook i powoduje niepotrzebne ponowienia wysyłki zdarzeń po stronie Stripe.

Uporządkuj także warstwę operacyjną. Firmowa skrzynka na własnej domenie kosztuje tyle, ile google workspace cena w planie podstawowym, czyli równowartość kilkudziesięciu złotych za użytkownika miesięcznie. Adres z tej domeny podajesz jako kontakt rozliczeniowy w Stripe oraz jako nadawcę potwierdzeń transakcji, co wyraźnie ogranicza trafianie wiadomości do folderu spam.

Jeżeli sklep stoi na WooCommerce, przygotuj dostępy administracyjne: wordpress logowanie z rolą administratora oraz osobne konto techniczne dla wdrożeniowca. Wcześniej wyeksportuj też katalog do feedu, bo google merchant odrzuca produkty bez ceny brutto, dostępności i unikalnego identyfikatora, a poprawki wprowadzane po starcie sprzedaży kosztują znacznie więcej czasu.

Konfiguracja krok po kroku: klucze, metody płatności i webhooki

Zacznij od kluczy. W panelu Stripe znajdziesz parę testową i produkcyjną. Klucz publiczny trafia do kodu front-endu, klucz tajny wyłącznie do zmiennych środowiskowych serwera. Nigdy nie umieszczaj go w repozytorium ani w plikach konfiguracyjnych motywu, bo to najczęstsza przyczyna kompromitacji konta w małych sklepach.

Właściwa konfiguracja sprowadza się do kilku kroków, które warto wykonać w ustalonej kolejności:

• Aktywuj Przelewy24 w sekcji metod płatności i ustaw PLN jako walutę prezentacji koszyka.
• Utwórz PaymentIntent po stronie serwera, przekazując kwotę w groszach oraz adres e-mail klienta, który jest wymagany przez tę metodę.
• Skonfiguruj adresy powrotu: osobny dla sukcesu, osobny dla anulowania i osobny dla nieudanej autoryzacji.
• Zarejestruj endpoint webhooka i zapisz sekret podpisu w konfiguracji serwera, poza repozytorium.
• Uruchom pełny scenariusz w trybie testowym, zanim przełączysz klucze na produkcyjne.

Webhook jest ważniejszy niż powrót użytkownika do sklepu. Klient potrafi zamknąć przeglądarkę zaraz po autoryzacji przelewu, więc zamówienie musi zostać opłacone na podstawie zdarzenia payment_intent.succeeded, a nie na podstawie wejścia na stronę podziękowania. Endpoint powinien odpowiadać kodem 200 w czasie krótszym niż dwie sekundy.

Zadbaj o idempotencję. Stripe ponawia dostarczenie zdarzenia przy każdym błędzie, więc ten sam identyfikator może dotrzeć kilkukrotnie. Zapisuj identyfikator zdarzenia w tabeli z unikalnym indeksem i odrzucaj duplikaty, zanim uruchomisz logikę magazynową. Bez tego mechanizmu jedno zamówienie potrafi zdjąć stan magazynowy dwa albo trzy razy.

Weryfikacja podpisu i kolejkowanie zdarzeń

Każde żądanie webhooka niesie nagłówek z podpisem. Porównaj go z sekretem endpointu przed jakimkolwiek przetwarzaniem, bo adres URL jest publiczny i podatny na fałszywe wywołania. Ciężkie operacje, takie jak generowanie faktury, wysyłka zlecenia do kuriera czy aktualizacja feedu produktowego, przenieś do kolejki zadań wykonywanej poza cyklem odpowiedzi.

Prowizje, wypłaty i realny wpływ na marżę

Koszt transakcyjny różni się między metodami, więc marżę trzeba liczyć osobno dla każdej z nich. Przelew bankowy jest zwykle tańszy od karty zagranicznej, a najdroższe pozostają płatności kartami wydanymi poza Europejskim Obszarem Gospodarczym, gdzie dochodzi jeszcze przewalutowanie i dodatkowa opłata naliczana przez operatora.

Przelicz to na konkretny asortyment. Przy koszyku za 349 PLN, w którym dominuje klawiatura mechaniczna z przełącznikami liniowymi, prowizja rzędu 2 procent to około 7 PLN. Przy zamówieniu firmowym za 6 000 PLN różnica między najtańszą a najdroższą metodą sięga już 90 PLN, czyli równowartości kilku godzin pracy serwisu.

Wypłaty trafiają na rachunek w cyklu dobowym lub tygodniowym, zależnie od ustawień i historii konta. Pierwsza wypłata bywa opóźniona nawet o siedem dni roboczych. Zaplanuj to w budżecie, jeśli finansujesz zatowarowanie z bieżącej sprzedaży, na przykład przy sezonowych dostawach peryferiów przed szczytem zakupowym.

Struktura kosztów wpływa również na politykę cenową. Tania klawiatura mechaniczna 60 procent za 249 PLN znosi prowizję bez problemu, ale przy akcesoriach za 39 PLN opłata stała zjada realną marżę. W takich przypadkach opłaca się ustawić minimalną wartość zamówienia albo dopłatę za wysyłkę poniżej progu.

Testy, bezpieczeństwo i najczęstsze błędy wdrożeniowe

Tryb testowy Stripe symuluje pełną ścieżkę Przelewów24 razem z ekranem wyboru banku oraz przyciskami autoryzacji i odrzucenia. Przejdź scenariusz sukcesu, anulowania, wygaśnięcia sesji oraz powrotu po zamknięciu karty przeglądarki. Każdy z nich powinien zostawić w bazie inny, jednoznaczny status zamówienia i inny komunikat dla klienta.

Najczęstszy błąd to waluta inna niż PLN w PaymentIntent, bo wtedy metoda po prostu nie pojawia się na liście. Drugi to brak adresu e-mail w obiekcie płatności. Trzeci to obsługa zamówienia w akcji powrotnej zamiast w webhooku, co generuje zamówienia bez płatności i płatności bez zamówień.

Bezpieczeństwo domykasz trzema nawykami: rotacją kluczy po każdej zmianie w zespole, brakiem logowania pełnych obiektów płatności do plików tekstowych oraz osobnymi kontami dla ludzi i dla integracji. Do tego dodaj monitoring nieudanych webhooków z alertem, bo cicha awaria kolejki zadań potrafi trwać całymi tygodniami.

Na koniec warstwa marketingowa. Sprawna kasa poprawia konwersję, ale ruch musi skądś przyjść, więc pozycjonowanie strony i przemyślane projektowanie stron internetowych są równie ważne co sama bramka. W praktyce pozycjonowanie strony w google dla frazy takiej jak klawiatura gamingowa mechaniczna bywa trudniejsze niż całe wdrożenie płatności.

Jak długo trwa integracja Stripe Przelewy24 sklepu na gotowej platformie?

Na gotowej platformie z oficjalną wtyczką realne wdrożenie zamyka się w jednym dniu roboczym: instalacja modułu, wklejenie kluczy, ustawienie webhooka i seria testów. Więcej czasu pochłania weryfikacja konta, która zależy od kompletności dokumentów firmy i potrafi zająć od kilku godzin do dwóch dni. W sklepie pisanym na zamówienie realistyczny budżet to od trzech do pięciu dni roboczych, licząc obsługę zdarzeń, idempotencję, zwroty, fakturowanie i testy regresyjne. Doliczam do tego jeszcze jeden dzień obserwacji produkcji po starcie, bo pierwsze prawdziwe transakcje ujawniają przypadki brzegowe niewidoczne w trybie testowym, na przykład podwójne kliknięcie przycisku zapłaty albo powrót z banku po wygaśnięciu sesji.

Czy integracja Stripe Przelewy24 sklepu obsługuje subskrypcje i płatności cykliczne?

Nie w sposób bezpośredni. Przelewy24 to metoda jednorazowa oparta na przekierowaniu do banku, więc nie da się nią automatycznie obciążyć klienta w kolejnym okresie rozliczeniowym. Jeżeli sprzedajesz abonament, na przykład dostęp do biblioteki materiałów albo pakiet serwisowy dla firm, pierwszą płatność możesz przyjąć przelewem, ale kolejne cykle wymagają zapisanej karty lub polecenia zapłaty. Praktyczne rozwiązanie wygląda tak: przy pierwszym zakupie proponujesz kartę jako domyślną metodę odnawiania, a przelew zostawiasz dla zamówień jednorazowych i zakupów firmowych z fakturą. Alternatywą jest model przedpłacony, w którym klient sam opłaca kolejny okres linkiem wysyłanym przed terminem wygaśnięcia usługi.

Co zrobić, gdy bank potwierdził płatność, a zamówienie w sklepie nadal jest nieopłacone?

Zacznij od panelu Stripe i sprawdź status PaymentIntent oraz historię dostarczania webhooków. W ponad połowie przypadków zdarzenie zostało wysłane, ale serwer sklepu zwrócił błąd 500 albo przekroczył limit czasu, więc płatność istnieje, a zamówienie nie zmieniło statusu. Ponów dostarczenie zdarzenia ręcznie z panelu i obserwuj logi aplikacji. Jeżeli endpoint odpowiada poprawnie, sprawdź, czy identyfikator zamówienia jest przekazywany w metadanych płatności i czy Twoja logika nie odrzuca zdarzenia jako duplikatu. Do czasu naprawy zabezpiecz proces zadaniem cyklicznym, które co kilkanaście minut porównuje płatności w Stripe z zamówieniami w bazie i domyka wykryte rozjazdy.