Czym jest PayU w PrestaShop i kiedy ma sens?

PayU to polski operator płatności. W PrestaShop podłączasz go jako bramkę: klient wybiera metodę w koszyku, płaci na stronie PayU albo w oknie BLIK, a wynik transakcji wraca do sklepu i przestawia status zamówienia. Bez tego drugiego elementu — informacji zwrotnej o transakcji — moduł jest tylko ozdobą checkoutu.

Standardowy zestaw metod to BLIK, karty Visa i Mastercard, Apple Pay, Google Pay, przelewy online z listy banków oraz płatności odroczone i raty. Dokładny zakres zależy od tego, co masz włączone na swoim POS-ie, więc najpierw sprawdź panel PayU, a dopiero potem planuj komunikację w sklepie.

• Przelew tradycyjny: klient sam robi przelew, Ty czekasz 0,5–2 dni robocze i weryfikujesz ręcznie — albo wysyłasz towar przed wpływem.
• Pobranie: płatność przy odbiorze, potwierdzenie dopiero u kuriera, prowizja po stronie przewoźnika, więcej zwrotów i niedoręczonych paczek.
• Bramka PayU: potwierdzenie w sekundach, status zmienia moduł, zero ręcznej pracy przy pojedynczym zamówieniu.

Zanim wpiszesz cokolwiek w moduł, musisz mieć podpisaną umowę z PayU i przejść KYC — weryfikację danych firmy, osoby reprezentującej i beneficjenta rzeczywistego. Po akceptacji dostajesz dostęp do panelu, a w nim identyfikator POS (punkt sprzedaży) oraz klucze API. Prowizje ustalane są indywidualnie i zależą od obrotu oraz metod płatności — stawki czytaj w swoim cenniku w panelu, nie w poradnikach z internetu.

PayU, Tpay czy Przelewy24? Porównuj cztery rzeczy: które metody są realnie dostępne dla Twojego profilu, wysokość prowizji i koszt zwrotu, tempo rozliczania wypłat oraz to, jak wygląda zwrot środka i reklamacja z poziomu sklepu. Dochodzi jakość API i wsparcia — jeśli wdrożenie robisz sam, brak sensownej dokumentacji kosztuje więcej niż różnica 0,2 pkt proc. w prowizji. Kontekst całego wdrożenia, razem z hostingiem i backupami, opisujemy w sekcji o organizacji wdrożenia PrestaShop.

Który moduł PayU wybrać do PrestaShop 1.7 i 8.x?

Na rynku są dwa typy rozwiązań: oficjalny moduł PayU (publikowany przez PayU i udostępniany w PrestaShop Addons) oraz moduły firm trzecich i pakiety „all-in-one” z marketplace’ów. Zacznij od oficjalnego — jest darmowy, a dokumentacja dotyczy tego samego produktu, który później wspiera operator.

Przed instalacją sprawdź trzy rzeczy: datę ostatniego wydania, deklarowane wsparcie dla wersji PrestaShop (1.7.x, 8.0, 8.1) i zakres PHP (7.4–8.2). Nie zakładaj, że „działa, bo inni mają” — jedna niezgodność z PHP kończy się białym ekranem w checkoutcie.

• Ostatnia aktualizacja starsza niż 12 miesięcy → traktuj jak ryzyko, nie jak oszczędność.
• Brak changelogu i numeru wersji → nie wiesz, co właściwie zmieniasz przy aktualizacji.
• Moduł nadpisuje szablony w /modules/<nazwa>/views/templates/ lub w motywie → po instalacji porównaj wygląd koszyka i strony potwierdzenia.
• Konflikt hooków: dwa moduły płatności rejestrują się na paymentOptions → w checkoutcie pojawia się jedna metoda albo żadna.

Własny moduł lub bezpośrednia integracja z REST API ma sens, gdy potrzebujesz niestandardowej logiki statusów (np. faktura wystawiana dopiero po potwierdzeniu transakcji), obsługujesz B2B z płatnością odroczoną i terminami, prowadzisz multistore z wieloma walutami albo chcesz spiąć płatności z ERP i magazynem. Wtedy moduł pisze się pod Twój proces, a nie proces dopasowuje się do modułu — ale licz się z utrzymaniem i testami po każdej aktualizacji PrestaShop. Jak nie wpaść w pułapki przy wyborze gotowych rozwiązań, opisujemy w artykule o modułach PrestaShop i ich wdrażaniu, a punkt startowy do własnej integracji znajdziesz w tekście o generatorze modułów PrestaShop. Struktura hooków i szablonów jest opisana w dokumentacji dla deweloperów PrestaShop.

Instalacja i konfiguracja modułu PayU krok po kroku

Zanim klikniesz cokolwiek, zrób kopię: zrzut bazy (mysqldump albo narzędzie hostingu) i archiwum plików. Jeśli masz taką możliwość, testuj na klonie sklepu na subdomenie z wyłączonym indeksowaniem — debug na produkcji przy 20 zamówieniach dziennie to zbędne ryzyko.

1. Instalacja: Zaplecze → Menedżer modułów → „Wgraj moduł” → wskaż ZIP. Alternatywnie wgraj katalog do /modules/ przez SFTP i zainstaluj z listy.
2. Klucze: w panelu PayU odczytaj POS ID, Client ID, Client Secret i Second Key. To cztery różne wartości — Second Key służy do weryfikacji podpisu powiadomień, a nie do autoryzacji API.
3. Wklejenie i zapis: wpisz dane w konfiguracji modułu. Jeśli moduł ma przełącznik środowiska, upewnij się, że po testach przełączasz go na produkcję razem z kompletem kluczy produkcyjnych.
4. Metody płatności: zaznacz tylko te, które faktycznie chcesz pokazywać (BLIK, karty, Apple Pay, Google Pay, przelewy, odroczone). Każda zbędna metoda to dodatkowe miejsce na pomyłkę klienta.
5. Waluty i minimalna kwota: ustaw obsługiwane waluty i minimalną wartość zamówienia per metoda — np. odroczone płatności przy koszyku za 15 zł generują odrzucenia.
6. Statusy: w Zamówienia → Statusy przygotuj cztery: „Oczekująca płatność”, „Płatność zaakceptowana” (oznaczony jako zapłacony), „Anulowana”, „Błąd płatności”. Podepnij je w module. Nie używaj dwóch statusów o tym samym ID.
7. Test: dodaj produkt za 1 zł, złóż zamówienie, przejdź do PayU, zapłać, wróć do sklepu i sprawdź status, e-mail oraz wpis w panelu PayU. Powtórz test także dla anulowania płatności.

Sandbox, produkcja i przełączanie środowiska

PayU utrzymuje dwa osobne środowiska i to jest źródło większości wdrożeniowych wpadek. Sandbox działa na hoście secure.snd.payu.com, produkcja na secure.payu.com. Token OAuth pobierasz z endpointu /pl/standard/user/oauth/authorize, ale na każdym środowisku z innym client_id (POS ID) i client_secret. Klucze z panelu sandbox nie zadziałają na produkcji i odwrotnie — nie ma tu wspólnego mianownika.

Karty testowe i testowy BLIK bierz wyłącznie z panelu sandbox PayU. Nie kopiuj numerów z poradników — PayU je rotuje, a po zmianie dostaniesz odrzucenie transakcji, którego będziesz szukał w module, choć problem jest w danych karty. Sandbox nie sprawdzi też realnego księgowania: statusy są symulowane, więc „działa na sandboxie” nie znaczy „działa na produkcji”.

W konfiguracji modułu sprawdzasz cztery pola: POS ID, Client Secret, drugi klucz (Second Key) do weryfikacji podpisu i przełącznik trybu testowego. Do tego adres powrotu (continueUrl) i adres powiadomień (notify_url). Ten drugi musi być publicznie dostępny — jeśli sklep stoi za basic auth, na firewallu z whitelistą IP albo w katalogu /dev/, PayU nie doręczy powiadomienia. Weryfikacja: w access logu serwera szukasz POST-a na ścieżkę kontrolera modułu i testujesz go ręcznie przez curl z zewnętrznej sieci.

Typowy błąd numer jeden: po wdrożeniu ktoś zostawia zaznaczony tryb testowy. Objaw jest cichy — zamówienia wchodzą, klienci widzą bramkę, ale płatności się nie księgują, a statusy stoją w oczekiwaniu. Drugi w kolejności to pozostawione zamówienia testowe i karty testowe w profilach klientów. Zanim wpiszesz klucze, ustal też, który moduł obsługuje płatności — piszemy o tym w materiale PrestaShop moduły: jak wybrać, wdrożyć i nie zepsuć sklepu.

Statusy zamówień, webhooki i potwierdzenia płatności

Status zamówienia w PrestaShop zmienia nie powrót klienta na stronę sklepu, a powiadomienie serwer-serwer od PayU. Schemat jest zawsze taki sam: klient składa zamówienie (status „Oczekiwanie na płatność”), moduł tworzy zamówienie w PayU i przekierowuje przeglądarkę, PayU autoryzuje płatność i wysyła POST na notify_url, moduł weryfikuje podpis i przestawia zamówienie na status z konfiguracji — najczęściej „Płatność zaakceptowana”. Klient, który zamknie kartę po zapłacie, nie psuje niczego, o ile notify dotarł.

Najczęstszy problem brzmi: „pieniądze są na koncie, a zamówienie wisi w oczekiwaniu”. Pięć przyczyn w kolejności sprawdzania:

• notify nie dotarł — WAF, ochrona anty-DDoS, basic auth, blokada po IP albo przekierowanie HTTP na HTTPS wykonane na metodzie POST;
• podpis nie przeszedł weryfikacji — drugi klucz z innego środowiska;
• moduł nie dopasował zamówienia — zmieniony koszyk między przekierowaniem a powrotem;
• brak ustawionego statusu docelowego dla płatności zakończonej;
• zadanie cykliczne nie działa i nikt nie dopytał PayU o status.

Diagnostykę zaczynasz od logów. W PrestaShop: Zaawansowane → Logi, tabela ps_log, filtr po nazwie modułu. Moduły płatności często piszą własny plik — sprawdź opcję logowania w konfiguracji oraz katalogi /var/logs/ i /app/logs/. Szukasz dwóch identyfikatorów: orderId z PayU i extOrderId, czyli numeru zamówienia ze sklepu. Z nimi zgłoszenie do PayU idzie w kilka minut, bez nich — w kilka dni.

Jako zabezpieczenie ustaw cron co 10–15 minut na odpytywanie API o status zamówień z ostatnich 24 godzin. PayU ponawia powiadomienia kilka razy, ale jeśli notify_url był niedostępny dłużej, ponowienia też przepadną. Powiadomienie musi kończyć się odpowiedzią HTTP 200 (MDN Web Docs); przekierowanie 301 lub 302 PayU potraktuje jak porażkę.

Najczęstsze błędy przy integracji PayU z PrestaShop

Zacznij od podziału: błąd jest w połączeniu, w danych albo w kolejności zdarzeń. 401 i 403 to zwykle pierwsza grupa — token OAuth nie powstaje, bo POS ID, Client Secret lub drugi klucz są błędne albo pochodzą z innego środowiska. Test ręczny: POST na endpoint autoryzacji z nagłówkiem Basic (Base64 z client_id:client_secret) i parametrem grant_type=client_credentials. 200 z access_token oznacza klucze poprawne, 401 — do wymiany. 403 częściej oznacza POS ID bez uprawnień do konkretnej metody (BLIK, raty) albo nieaktywną umowę.

Druga grupa to PHP. Brak rozszerzenia cURL sprawdzisz w Zaawansowane → Informacje; objaw to biały ekran lub 500 przy przekierowaniu do bramki. Stare PHP bez aktualizacji modułu daje ostrzeżenia i błędy typu Call to undefined function. Wyłączony lub niepełny SSL kończy się odrzuceniem powiadomienia albo blokadą przekierowania — certyfikat musi obejmować domenę powrotu.

Niezgodność kwoty lub waluty: koszyk pokazuje 129,99 PLN, a do PayU leci 129.99 albo kwota po innym zaokrągleniu. Winne są zwykle separator dziesiętny przy imporcie, rabat naliczany w module, a nie w koszyku, oraz multistore z inną walutą zamówienia. Efekt: PayU odrzuca zamówienie i transakcja w ogóle nie powstaje.

Duplikaty mają dwa źródła. Dwa zamówienia po dwukrotnym kliknięciu „Zamawiam” to wina modułu — nie blokuje przycisku. Duplikat po powiadomieniu to brak idempotencji webhooka: PayU ponawia POST-y, a sklep przetwarza każdy osobno. Lekarstwo: przed utworzeniem zamówienia sprawdź, czy nie istnieje już zamówienie z tym samym extOrderId.

BLIK: kod ma 6 cyfr i krótki czas życia, więc brak kodu to najczęściej klient, który nie zdążył przepisać go z aplikacji banku. Druga przyczyna to numer telefonu ze spacjami, myślnikami albo bez prefiksu krajowego — BLIK wymaga numeru powiązanego z kontem. Trzecia to timeout bramki przy wolnym łączu. Nie odświeżaj strony w trakcie potwierdzania kodu. Jeśli wdrożenie robisz od zera, kolejność kroków opisujemy w organizacji wdrożenia PrestaShop krok po kroku.

Bezpieczeństwo, zgodność i zwroty przez PayU

Integracja PayU nie kończy się na kluczach API. Trzy rzeczy trzeba domknąć przed startem: szyfrowanie, zakres przekazywanych danych i obsługa zwrotów.

HTTPS. Katalog, koszyk i panel administracyjny muszą działać po HTTPS, a certyfikat musi być ważny z zapasem. Powiadomienia PayU o zmianie statusu płatności przychodzą na adres Twojego sklepu — jeśli certyfikat wygaśnie albo TLS zostanie wyłączony, potwierdzenia przestaną dochodzić i zamówienia zostaną w statusie „Oczekiwanie na płatność”, mimo że klient zapłacił. Ustaw przypomnienie o wygaśnięciu certyfikatu minimum 30 dni wcześniej. Podstawy protokołu opisuje dokumentacja HTTP w MDN.

PCI DSS. Przy przekierowaniu na stronę PayU dane karty nie przechodzą przez serwer sklepu i nie są nigdzie w PrestaShop zapisywane. To najbezpieczniejszy wariant i realnie najmniejszy zakres PCI DSS. Nie buduj własnego formularza na kartę i nie dopuszczaj wpisywania numeru karty w komentarzu do zamówienia — to od razu wciąga sklep w poważniejszy zakres i audyt.

Zwroty i refundy. Przycisk zwrotu w PrestaShop nie oddaje pieniędzy — zmienia stan magazynu i status zamówienia. Zwrot środków robisz w panelu PayU (Zwroty) albo przez API. Kolejność jest zawsze ta sama: zwrot w PayU, potwierdzenie, status w PrestaShop, korekta faktury. Odwrotna kolejność kończy się zamówieniem oznaczonym jako zwrócone, za które klient nie dostał pieniędzy.

Faktury. Sprawdź, przy którym statusie PrestaShop wystawia dokument. Jeśli faktura powstaje przy „Oczekiwanie na płatność”, będziesz mieć dokumenty do porzuconych koszyków. Data płatności na fakturze powinna zgadzać się z datą transakcji w PayU.

RODO. Do PayU trafiają: imię i nazwisko, e-mail, adres, kwota, identyfikator zamówienia i adres IP. Ten zakres musi być widoczny w polityce prywatności razem ze wskazaniem PayU jako odbiorcy danych.

Logowanie zdarzeń wdrażaj, gdy masz kilkadziesiąt zamówień dziennie, własne statusy albo spory z klientami. Zapisuj surowe powiadomienie: czas, numer zamówienia, status, kwotę i metodę. Wybór gotowego rozwiązania opisujemy w materiale o modułach PrestaShop.

Ile trwa i ile kosztuje wdrożenie PayU w PrestaShop?

Widełki zależą od tego, ile pracy pokrywa gotowy moduł, a ile trzeba dopisać. Poniżej realne przedziały przy założeniu, że klucze i konfiguracja statusów są już przemyślane.

Koszt pracy liczę przy stawce 200 zł netto za godzinę — to typowy poziom dla wdrożeń e-commerce w Polsce, ale każdy wykonawca wycenia inaczej, więc traktuj to jako punkt odniesienia do porównania ofert, a nie jako cennik.

Co wydłuża pracę. Liczba metod płatności włączonych w module, liczba własnych statusów zamówień, wersja PrestaShop (1.7 i 8.x mają różne moduły i różne hooki), motyw nadpisujący szablony, wielojęzyczność i wielosklep, tryb B2B oraz płatności częściowe. Każda z tych rzeczy dodaje od kilkudziesięciu minut do kilku godzin, bo wymaga testu po stronie PayU i po stronie sklepu.

Moduł czy własny kod. Gotowy moduł obsługuje standardowy sklep: katalog, koszyk, jedna waluta, jedna metoda płatności. Własną integrację rozważ, gdy proces odbiega od standardu — na przykład zamówienia B2B z odroczonym terminem, płatność częściowa, wiele sklepów obsługiwanych jednym kontem PayU albo nietypowe mapowanie statusów. Prosty przelicznik: jeśli gotowy moduł kosztuje w przeliczeniu na roboczogodziny mniej niż kilka godzin pracy, a własna integracja to 20–40 godzin, wersja własna ma sens tylko wtedy, gdy daje funkcję, której moduł naprawdę nie ma. Sprawdź aktualną cenę i zgodność modułu z Twoją wersją PrestaShop przed zakupem — te informacje zmieniają się z miesiąca na miesiąc. Przy pisaniu własnego modułu korzystaj z dokumentacji dla deweloperów PrestaShop.

Opieka po wdrożeniu. Aktualizacja PrestaShop albo samego modułu potrafi rozjechać mapowanie statusów i wtedy płatności przestają się księgować. Ustal, kto reaguje w takiej sytuacji i w jakim czasie — czy jest to jedna osoba w firmie, czy wykonawca z określonym czasem reakcji. Zakres wdrożenia i opieki nad sklepem PrestaShop opisujemy razem z tym, co wchodzi w stałą obsługę.

Checklista wdrożenia PayU w PrestaShop

Lista do przejścia punkt po punkcie. Odhaczaj od góry, nie pomijaj testów płatności — to jedyny moment, w którym błędy nie kosztują jeszcze utraconych zamówień.

• Klucze sandbox i produkcyjne trzymane osobno; na produkcji nie ma żadnej wartości testowej.
• Certyfikat HTTPS ważny, panel administracyjny również po HTTPS.
• Adres powrotu i adres powiadomień ustawione w panelu PayU zgodnie z domeną produkcyjną.
• Statusy zamówień: „Oczekiwanie na płatność”, „Płatność zaakceptowana”, „Płatność odrzucona”, „Anulowana”, „Zwrócono” — każdy z własnym szablonem e-maila.
• Faktura generowana dopiero po potwierdzeniu płatności.
• Adres powiadomień dostępny publicznie — nie blokuje go .htpasswd, WAF ani moduł zabezpieczający.
• Kopia bazy danych i plików wykonana przed wdrożeniem.
• Polityka prywatności i regulamin zawierają informację o przekazaniu danych do PayU.
• Osoba odpowiedzialna za dostęp do panelu PayU wskazana, hasła nie krążą w mailach.
• Notatka wewnętrzna: gdzie leżą klucze, kto je rotuje i kiedy.

Weryfikacja produkcji. Po testach w sandboxie wykonaj jedną prawdziwą płatność na niewielką kwotę, najlepiej własną kartą. Sprawdź kolejno: status zamówienia, e-mail potwierdzający, fakturę i obecność transakcji w panelu PayU. Następnie zwróć tę płatność i sprawdź, czy status oraz korekta dokumentu zadziałały tak samo jak w sandboxie.

Monitoring po starcie. Ustaw alert na zamówienia, które wiszą w „Oczekiwanie na płatność” dłużej niż kilkanaście minut, i na powiadomienia zwracające błąd serwera. Przeglądaj logi modułu oraz logi serwera pod kątem wywołań adresu powiadomień. Dopisz do kalendarza termin wygaśnięcia certyfikatu. Jeśli w sklepie działa kilka modułów płatności, obejrzyj też materiał o modułach PrestaShop — konflikty między nimi zdarzają się częściej niż awarie samego PayU.

Najczęstsze błędy i jak je wykryć

Lista kontrolna do odklikania

• Aktywna umowa i KYC w PayU — Sprawdź przed pierwszym uruchomieniem na produkcji — bez zaakceptowanej umowy nie przyjmiesz prawdziwych płatności, nawet przy poprawnych kluczach.
• POS ID zgodny ze środowiskiem — Porównaj wartość w konfiguracji modułu z panelem PayU. Sandbox i produkcja mają osobne identyfikatory.
• Client ID i Client Secret — Sprawdź po każdej zmianie hasła lub uprawnień w panelu PayU — rotacja danych potrafi unieważnić integrację.
• Second Key — Zweryfikuj przed testem płatności; brak tego klucza daje błędy autoryzacji przy części metod.
• Włączone metody płatności — Ustaw tylko te, które masz w umowie (BLIK, karty, Apple Pay, Google Pay, przelewy online, płatności odroczone) i ukryj pozostałe, żeby klient nie trafiał na niedziałającą płatność.
• Obsługa walut — Sprawdź, czy każda waluta aktywna w sklepie jest dopuszczona po stronie operatora — inaczej transakcja zostanie odrzucona.
• Minimalna kwota zamówienia — Zweryfikuj po zmianie cennika lub promocji; zbyt niska kwota bywa odrzucana przez operatora.
• Mapowanie statusów zamówień — Sprawdź, czy każdy status z modułu (oczekująca, opłacona, anulowana, błąd płatności) istnieje w PrestaShop i jest przypisany do właściwego stanu.
• Publiczny dostęp do notify_url — Najlepiej przetestuj z zewnętrznej sieci — VPN, basic auth i restrykcyjny WAF to najczęstsze przyczyny braku powiadomień.
• SSL i cURL — Sprawdź, czy certyfikat jest ważny i czy rozszerzenie cURL działa na wersji PHP używanej przez sklep.
• Pełny test w sandboxie — Dodaj produkt, przejdź do PayU, zapłać testową kartą lub BLIK-iem i wróć do sklepu. Sprawdź, czy status zmienił się automatycznie.
• Test płatności nieudanej — Sprawdź, czy anulowana transakcja ustawia status błędu i czy zamówienie nie blokuje się w koszyku.
• Ponawianie powiadomień, cron — Ustaw mechanizm zabezpieczający na wypadek chwilowej niedostępności sklepu — jedno nieodebrane powiadomienie nie powinno zostawiać zamówienia na zawsze w zawieszeniu.
• Kopia bazy i plików przed aktualizacją modułu — Rób kopię zawsze, gdy aktualizujesz moduł płatności lub motyw — to jedyna szybka droga powrotu, gdy coś przestanie działać.

Najczęściej zadawane pytania

Źródła i materiały

• Google Search Central – tworzenie treści dla ludzi
• Google Search Central – dane strukturalne
• Google Search Central – Core Web Vitals
• PrestaShop – dokumentacja dla deweloperów
• MDN Web Docs – HTTP