PayPal w PrestaShop – które warianty integracji masz do wyboru

Największy bałagan w projektach z PayPalem nie bierze się z kodu, a z nazw. W panelu modułów możesz mieć jednocześnie „PayPal”, „PayPal Standard” i wtyczkę zewnętrznego dostawcy, a każda z nich rozmawia z innym API. Zanim cokolwiek klikniesz, ustal, którą ścieżką idziesz.

• PayPal Standard / Express Checkout – starsza generacja: komunikacja przez NVP/SOAP, potwierdzenia po IPN, klient przenoszony na stronę PayPala. W wielu sklepach działa do dziś, ale nie dostaje nowych funkcji i słabiej znosi wymogi silnego uwierzytelniania w UE.
• PayPal Commerce Platform – aktualny standard: REST API, webhooki, obsługa 3D Secure/SCA i płatności kartą obok przycisku PayPal. Na tej ścieżce opierają się nowe integracje i nowe moduły.

Po stronie konta potrzebujesz konta Business (Personal odpada), potwierdzonego e-maila oraz uzupełnionych danych firmy i rachunku bankowego. Sprawdź to wcześniej – weryfikacja bywa ręczna i zajmuje od kilku godzin do kilku dni roboczych. Te same dane posłużą potem do logowania w panelu deweloperskim, gdzie tworzysz aplikację REST i pobierasz Client ID oraz Secret.

Samych wariantów wdrożenia są cztery: oficjalny moduł PrestaShop, wtyczka z marketplace (płatna subskrypcja, czasem z kodem zamkniętym), własny moduł pod konkretny sklep oraz integracja REST bez modułu – np. gdy płatność odpala system zamówień poza PrestaShopem.

Dobór sprowadza się do modelu sprzedaży: mały sklep detaliczny w Polsce poradzi sobie na oficjalnym module; w B2B najpierw sprawdź, czy klienci faktycznie zapłacą PayPalem, bo często wygrywa przelew i płatność odroczona; sklep eksportowy z wieloma walutami potrzebuje Commerce Platform i modułu, który obsługuje webhooki oraz przelicza waluty bez sztywnego kursu.

Kolejność działań po stronie sklepu i klienta rozpisaliśmy osobno w materiale o organizacji wdrożenia modułu PayPal w PrestaShop.

Oficjalny moduł vs wtyczka z marketplace vs własny moduł – jak wybrać

Zadaj trzy pytania: kto to utrzyma, czy mam dostęp do kodu i co się stanie za 12 miesięcy. Odpowiedzi rozstrzygają więcej niż lista funkcji na karcie produktu.

Koszty. Licencje wtyczek są wyceniane w euro i rozliczane rocznie. Kwoty się zmieniają, więc sprawdź aktualny cennik, ale do kalkulacji przyjmij trzy lata, nie pierwszy rok. Kluczowe jest to, co dzieje się po wygaśnięciu subskrypcji: czy moduł dalej przyjmuje płatności, a tylko nie dostaje aktualizacji, czy przestaje działać lub wsparcie przestaje odpowiadać. To różnica między zamrożonym kodem a wyłączoną płatnością. Policz też koszt przestoju: przy 50 zamówieniach dziennie i średniej wartości 200 zł każdy dzień bez płatności to około 10 tys. zł obrotu.

Dostęp do kodu. Pliki zakodowane ionCube albo Zend to brak możliwości hotfixu w piątek wieczorem. Aktualizacje. Sprawdź datę ostatniego wydania i changelog. PrestaShop 1.7 i 8.x różnią się warstwą Symfony i hookami, więc moduł bez wydania od dwóch lat nie wjedzie na 8.x bez poprawek. Cykl życia modułów opisuje dokumentacja dla deweloperów PrestaShop.

Kiedy własny moduł wygrywa: koszyk z rabatami liczonymi po stronie serwera, wielowalutowość z własnym kursem i zaokrąglaniem, integracja z ERP (statusy, faktury, magazyn), płatność częściowa lub dopłata po złożeniu zamówienia.

Sygnały ostrzegawcze w wtyczkach z marketplace: brak wsparcia webhooków i sprawdzanie statusu po cronie; zapisywanie transakcji we własnych tabelach zamiast powiązania z zamówieniem; brak obsługi SCA i rosnące odrzucenia; brak zwrotów z panelu sklepu; zero logów, gdy płatność nie dojdzie.

Jeśli w projekcie jest kilka integracji naraz, uporządkuj je wspólnie – patrz integracje z PrestaShop: organizacja pracy i wdrożenia.

Konfiguracja krok po kroku: konto, aplikacja, sandbox i tryb live

Zacznij od konta Business i domknij weryfikację, zanim dotkniesz modułu. Potem zaloguj się tym samym kontem do panelu deweloperskiego i utwórz aplikację osobno dla środowiska Sandbox i osobno dla Live. Typ aplikacji: Merchant. Zaznacz tylko te uprawnienia, których użyjesz – jeśli nie chcesz zapisywać kart, nie włączaj funkcji powiązanych z przechowywaniem danych karty.

Pobierz Client ID i Secret. Secret pokazuje się raz, więc wrzuć go do menedżera haseł, a nie do repozytorium. Dla trybu live wygeneruj nowe klucze – kopiowanie sandboxowych to najczęstszy błąd przy przełączaniu.

Sandbox. W panelu utwórz dwa konta testowe: Business (sprzedawca) i Personal (kupujący). Do sandboxa logujesz się osobnym logowaniem – dane z konta live nie zadziałają. Karty testowe generuje narzędzie w panelu; dostępne są też scenariusze 3D Secure: płatność zaakceptowana i odrzucona. Przetestuj oba, bo dopiero odrzucenie pokazuje, czy sklep poprawnie oznacza nieudaną transakcję.

Webhooki. Adres musi być publiczny i po HTTPS. Nie lokalny host, nie adres w sieci wewnętrznej, nie endpoint za logowaniem – PayPal nie zaloguje się do panelu sklepu. Certyfikat musi mieć pełny łańcuch. Endpoint powinien odpowiadać kodem 2xx w kilka sekund i nie wykonywać ciężkiej pracy – zapisz zdarzenie i przetwórz je w cronie. Kody odpowiedzi i zachowanie przekierowań opisuje dokumentacja MDN dotycząca HTTP. Jeśli sklep stoi za CDN lub WAF, po pierwszym teście zajrzyj w logi serwera – ruch z PayPala bywa tam blokowany.

Przejście na live. Zmieniają się tylko klucze i adres webhooka; konfiguracja koszyka zostaje. Po przełączeniu wykonaj jedną realną płatność na małą kwotę, a potem zwrot z panelu PayPala i sprawdź, czy status zamówienia się zaktualizował. W PrestaShop ustaw waluty i kursy, ograniczenia krajów i stref, geolokalizację oraz kolejność metod płatności w preferencjach. Przy testach wyłącz cache. Samą konfigurację modułu rozpisaliśmy w tekście PayPal w PrestaShop: szybka konfiguracja krok po kroku.

PSD2, SCA i 3D Secure – co musi spełnić polski sklep

SCA (silne uwierzytelnianie klienta) to wymóg PSD2: przy płatności w EOG trzeba potwierdzić tożsamość kupującego dwoma z trzech elementów — czymś, co wie (hasło), czymś, co ma (telefon, aplikacja banku) i czymś, czym jest (biometria). W praktyce w PayPal uwierzytelnienie prowadzi PayPal jako dostawca usług płatniczych i podmiot obsługujący 3D Secure. Klient loguje się do konta PayPal albo przechodzi challenge 3DS wystawiony przez swój bank. W sklepie nie integrujesz 3DS osobno i nie potrzebujesz do tego dodatkowej wtyczki.

Trzy wyjątki, które realnie zobaczysz w rozliczeniach:

• MIT (merchant-initiated transaction) – obciążenia cykliczne i subskrypcje. Pierwsza płatność przechodzi z SCA, kolejne mogą iść bez uwierzytelnienia, jeśli konto ma włączone transakcje referencyjne (Reference Transactions), a klient zaakceptował zgodę na obciążenia. Sprawdź to przed wdrożeniem subskrypcji — bez tej zgody drugie obciążenie padnie i klient dostanie maila o nieudanej płatności.
• Low value – transakcje poniżej ok. 30 EUR, z limitem 5 kolejnych płatności lub 100 EUR łącznie.
• TRA (Transaction Risk Analysis) – wyjątek liczony po wskaźniku oszustw operatora. Nie wpływasz na niego konfiguracją sklepu.

Co to oznacza dla Ciebie: nazwa prawna na koncie PayPal musi zgadzać się z KRS lub CEIDG, kwota i waluta w zamówieniu muszą pasować do groszaka do tego, co wysyła moduł, a adres dostawy musi być adresem z transakcji. Gdy kwoty się rozjeżdżają (typowo przez zaokrąglenia w koszyku albo rozbieżny podatek), transakcja ląduje jako PENDING i rośnie ryzyko przegranego sporu. Efektem ubocznym SCA jest mniej porzuceń koszyka — klient nie jest wyrzucany do banku, tylko zostaje w PayPalu. Same ustawienia modułu i dane wysyłane do API opisujemy w dokumentacji deweloperskiej PrestaShop oraz w materiale o szybkiej konfiguracji PayPal w PrestaShop. Kolejność prac po stronie sklepu rozpisaliśmy w tekście o organizacji wdrożenia modułu PayPal.

Zwroty, dysputy i chargebacki – obsługa po sprzedaży

Zwrot w panelu PayPal nie aktualizuje zamówienia w PrestaShop. To najczęstsza pułapka po wdrożeniu: księgowość widzi korektę, a w sklepie zamówienie dalej wisi jako opłacone i zrealizowane.

Kolejność działań przy zwrocie:

• Jeśli moduł ma przycisk zwrotu przy zamówieniu — użyj go. Kwota wraca przez API i status zamówienia zmienia się sam.
• Ręczny zwrot robisz w panelu PayPal: Activity → wybrana transakcja → Refund → pełny albo kwota częściowa. Zwrot idzie na źródło płatności; karta księguje się zwykle 3–5 dni roboczych, czasem dłużej — przygotuj szablon maila, bo klienci piszą po dwóch dniach.
• W PrestaShop wystaw korektę (credit slip) i zaznacz „zwróć produkty do magazynu” tylko wtedy, gdy towar fizycznie do Ciebie wrócił. Sam zwrot płatności nie zdejmuje i nie dodaje stanów.
• Numer transakcji PayPal (Transaction ID) wpisz w uwagach do zamówienia i do korekty faktury. Bez tego nie połączysz dokumentu z przepływem pieniędzy przy kontroli.

Nie robimy zwrotów „przelewem na telefon”. Tracisz wtedy dowód i prawo do ochrony sprzedawcy. Przy reklamacjach wrzucaj do panelu: potwierdzenie nadania i dostawy ze śledzeniem, korespondencję mailową, logi zamówienia (IP, data, statusy), regulamin z potwierdzoną akceptacją. Ochrona sprzedawcy nie obejmuje towarów niematerialnych i usług — tam wygrywasz tylko dokumentacją.

Jeśli odbierasz powiadomienia webhook, odpowiadaj kodem 200 — błędy powodują ponowienia i duplikaty operacji, co przy zwrotach boli podwójnie (specyfikacja HTTP i kody statusu w MDN). Zwroty muszą też mieć osobny status zamówienia, inaczej raport sprzedaży pokaże przychód, którego nie było — opisaliśmy to przy okazji wdrożenia DataLayer w PrestaShop. Całość procesów okołopłatnościowych porządkuje materiał o integracjach z PrestaShop.

Ile realnie kosztuje PayPal w polskim sklepie

Koszt PayPala w polskim sklepie składa się z trzech pozycji: prowizji od transakcji, opłaty stałej i przewalutowania, do których dochodzi wypłata środków oraz ewentualne opłaty za spory.

• Prowizja i opłata stała. Stawka zależy od obrotów, rynku kupującego i negocjacji. Dla małego sklepu w Polsce licz się z poziomem rzędu 2,9–3,4% + ok. 1 zł od transakcji krajowej; transakcje zagraniczne są droższe. Aktualną stawkę sprawdź w cenniku merchant na swoim koncie — nie opieraj się na cenniku z bloga sprzed dwóch lat.
• Przewalutowanie. Pojawia się, gdy klient płaci w EUR lub USD, a Ty trzymasz saldo w PLN albo masz włączoną automatyczną konwersję. To nie jest osobna linia na wyciągu, tylko spread w kursie. Przy eksporcie to często większy koszt niż sama prowizja.
• Wypłata. Przelew na konto firmowe w PLN księguje się zwykle 1–2 dni robocze; pierwsza wypłata po weryfikacji konta bywa wolniejsza.

Poniższa tabela to rachunek na jawnych założeniach, a nie cennik dostawców. Podstaw własne stawki z umów i policz to samo na swoich danych: średni koszyk × udział metody × liczba zamówień w miesiącu.

Konwersja: w płatnościach krajowych BLIK, Przelewy24 i InPost Pay wygrywają przyzwyczajeniem i brakiem logowania. PayPal wygrywa tam, gdzie klient nie ma polskiej karty: eksport, klienci z UE i USA, B2B kupujące na fakturę z zagranicy, kursy i usługi cyfrowe. Nie wyłączaj P24 na rzecz PayPala — to nie albo-albo. Po włączeniu nowej metody sprawdź w wdrożeniu GA4 eCommerce, czy faktycznie rośnie udział zamówień, a nie tylko liczba kliknięć. Jeśli nie wiesz, kto ma liczyć te stawki i porównywać warianty wdrożenia, punktem wyjścia jest materiał o kosztach wdrożenia PrestaShop.

Najczęstsze błędy konfiguracji i jak je zdiagnozować

Trzy objawy odpowiadają za większość zgłoszeń do wsparcia przy PayPal w PrestaShop: status zamówienia nie zmienia się po opłaceniu, zamówienie tworzy się podwójnie, a klucze z sandbox trafiają na produkcję. Każdy z nich da się zdiagnozować lokalnie, bez pisania do helpdesku.

Status nie zmienia się po opłaceniu. Zamówienie stoi na „Oczekiwanie na płatność PayPal”, choć w panelu PayPal transakcja ma status Completed. Prawie zawsze winny jest webhook: nie doszedł, doszedł pod zły adres albo zwrócił kod inny niż 200. Diagnoza w trzech krokach: (1) Advanced Parameters → Logs w back office, tam moduł zapisuje własne błędy, (2) panel PayPal Developer → twoja aplikacja → Webhooks → lista zdarzeń z kodem odpowiedzi, jaką zwrócił twój sklep, (3) access.log i error.log serwera. Jeśli zdarzenia mają status 500, sprawdź, czy WAF lub proxy nie blokuje adresów IP PayPal. Jeśli nie ma ich wcale — adres webhooka jest zły albo aplikacja nie ma subskrypcji na zdarzenie typu PAYMENT.CAPTURE.COMPLETED.

Duplikaty zamówień. Powstają, gdy powrót klienta z PayPal (return URL) i webhook tworzą zamówienie niezależnie — dwa kody ścieżki, dwa wpisy w bazie. Drugi wariant to podwójne kliknięcie „Zapłać” albo odświeżenie strony powrotu. Lekarstwo jest jedno: identyfikacja po identyfikatorze transakcji i wspólny punkt tworzenia zamówienia dla obu ścieżek.

Sandbox pomieszany z live. Najczęstsza przyczyna to podmiana tylko części danych: nowe klucze, stare adresy powrotu, wpisy w ps_configuration z poprzedniego środowiska. Porównaj parę client_id/secret, adresy powrotu i anulowania oraz wyczyść cache po zmianie. Kody zwrotu warto czytać ze zrozumieniem — opis znajdziesz w dokumentacji HTTP: Hypertext Transfer Protocol w MDN Web Docs. Diagnozę zacznij od uporządkowania środowisk zgodnie z zasadami organizacji wdrożenia płatności PayPal w PrestaShop.

Testy przed uruchomieniem – checklist wdrożeniowy

Checklistę uruchomieniową traktuj jak listę zadań z kryterium zaliczenia. Nie „przetestowaliśmy PayPal”, tylko „każdy scenariusz z tabeli przeszedł i mam na to numer transakcji lub zrzut ekranu”.

• Płatność udana — zamówienie dostaje status „Płatność zaakceptowana”, e-mail do klienta wychodzi, stan magazynowy spada o zamówioną ilość.
• Anulowanie — klient wraca przez przycisk anuluj; koszyk zostaje nienaruszony, nie powstaje zamówienie „oczekujące” na płatność.
• Zwrot pełny — wykonany z panelu PayPal; sprawdź, czy zamówienie przechodzi w status zwrotu i czy generuje się dokument korygujący.
• Zwrot częściowy — kwota niższa niż zamówienie. Najczęstszy błąd: status się nie zmienia, a księgowość widzi pełny zwrot.
• Reklamacja (dispute/chargeback) — zgłoś w sandbox testowe obciążenie zwrotne i sprawdź, czy sklep w ogóle pokazuje informację o sporze.
• Płatność z 3DS — użyj karty testowej wymuszającej uwierzytelnienie; bez tego nie wiesz, czy sklep obsłuży wyzwanie SCA i powrót po nim.

Ostatni etap przed live: jedno prawdziwe zamówienie na symboliczną kwotę (np. 1 zł) z prawdziwej karty, na produkcyjnych kluczach. Nie pomijaj tego kroku — sandbox nie odzwierciedla reguł ryzyka ani limitów konta live.

Waluta obca i mobile. Złóż zamówienie w EUR lub USD i porównaj kwotę w sklepie, w PayPal i na dokumencie — różnice z przewalutowania muszą zgadzać się z tym, co obiecujesz klientowi. Na telefonie sprawdź, czy przycisk płatności nie ucieka pod stopkę i czy powrót z aplikacji PayPal wraca do właściwego kroku zamówienia.

E-maile. Przejdź przez International → Translations → E-mails i sprawdź szablony płatności oraz order_conf — czy zawierają numer transakcji i kwotę. Osobno zweryfikuj powiadomienia wewnętrzne dla obsługi. Samą konfigurację modułu opisujemy w materiale szybka konfiguracja PayPal w PrestaShop krok po kroku. Jeśli modyfikujesz kod modułu, punktem wyjścia jest dokumentacja deweloperska PrestaShop.

Kiedy PayPal warto dodać, a kiedy odpuścić

PayPal nie jest uniwersalnym lekiem na konwersję. Realnie podnosi ją tam, gdzie klient ma ograniczone zaufanie do sklepu albo nie chce podawać danych karty: w sklepach z ruchem zagranicznym, z koszykiem liczonym w setkach złotych i przy widocznych odrzuceniach płatności kartą. Wtedy działa jak warstwa zaufania — sprzedawca nie dostaje numeru karty, a klient kończy zakup w kilka sekund, bo dane już ma zapisane w koncie PayPal.

Kiedy odpuścić. Gdy większość zamówień pochodzi z Polski i klient płaci BLIK-iem lub szybkim przelewem, a w analityce nie widzisz porzuconych koszyków z komentarzem o braku PayPal. Wtedy każda dodatkowa metoda to kolejne pole do utrzymania: obsługa sporów, uzgadnianie salda, prowizja, kolejny zestaw kluczy do rotacji i jeszcze jeden scenariusz w testach przed każdym wdrożeniem. Prowizja zależy od rynku i warunków na twoim koncie — sprawdź ją w cenniku w panelu, zanim włączysz metodę „na próbę” i zostawisz na rok bez przeglądu.

Strategia: metoda uzupełniająca. Płatności lokalne zostają na pierwszym miejscu, PayPal wchodzi jako druga lub trzecia opcja dla klientów, którzy nie chcą podawać karty. Taki układ porządkuje też konfigurację — jeśli wszystkie metody korzystają z jednego modelu statusów zamówienia i jednego sposobu powiadamiania, mniej rzeczy się rozjeżdża przy zmianach.

Rekomendacja kolejnego kroku. Jeśli PayPal już działa, ale nie wiesz, czy webhooki dochodzą i czy statusy są spójne — zacznij od audytu obecnej konfiguracji, zanim cokolwiek dołożysz. Szersze spojrzenie na całość połączeń opisujemy w materiale o organizacji pracy przy integracjach z PrestaShop. Jeśli dopiero dodajesz metodę — zaplanuj wdrożenie od zera: wybór wariantu, konto i aplikacja, konfiguracja, checklista testów, dopiero potem live.

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

Lista kontrolna do odklikania

• Konto PayPal Business zweryfikowane — Sprawdź przed konfiguracją modułu — konto prywatne nie wystarczy do przyjmowania płatności i integracji przez REST API.
• Dane firmy zgodne z wpisem w CEIDG/KRS — Zweryfikuj przed pierwszym uruchomieniem live. Rozbieżność nazwy lub adresu wychodzi dopiero przy reklamacji albo wypłacie środków.
• Dostęp do PayPal Developer dla właściwego konta — Zaloguj się i sprawdź, czy widzisz zakładkę aplikacji. Dostęp musi mieć właściciel konta, a nie tylko wykonawca.
• Aplikacja REST i zapisane Client ID oraz Secret — Utwórz aplikację w panelu Developer i zapisz oba klucze w sejfie hasłem — nie w repozytorium i nie w mailu.
• Osobne klucze dla sandbox i live — Sprawdź w panelu Developer przed przełączeniem środowiska. Pomyłka kluczy to najczęstsza przyczyna „działało w testach, nie działa na produkcji”.
• Konto testowe kupującego i karty testowe — Potrzebne do testów w sandbox. Sprawdź kilka scenariuszy: płatność udana, odrzucona i wymagająca uwierzytelnienia.
• Publiczny adres HTTPS dla webhooków — Sprawdź, czy URL jest osiągalny z internetu i ma ważny certyfikat. Bez tego statusy zamówień nie wrócą automatycznie.
• Lista nasłuchiwanych zdarzeń webhooka — Ustal, które zdarzenia obsługuje moduł i czy pokrywają Twoje scenariusze (płatność, zwrot, reklamacja).
• Zgodność walut i krajów między sklepem a kontem PayPal — Sprawdź przed live — waluta, której nie ma na koncie, zablokuje część transakcji.
• Kolejność metod płatności w koszyku — Sprawdź po dodaniu modułu, na komputerze i na telefonie. Kolejność wpływa na to, co wybiera klient.
• Pełny test ścieżki zakupowej — Od koszyka do dokumentu sprzedaży: płatność, powrót, e-mail, faktura, stan magazynowy.
• Test zwrotu pełnego i częściowego — Wykonaj w sandbox przed live i zapisz, które kroki są ręczne, a które dzieją się same.
• Ograniczenia geograficzne i geolokalizacja — Sprawdź, jeśli sprzedajesz za granicę — inaczej pokażesz metodę płatności, której klient nie może użyć.
• Backup bazy i plików przed aktualizacją modułu — Rób przed każdą aktualizacją, także poprawkową. Aktualizacja wtyczki płatności potrafi nadpisać szablony.

Najczęściej zadawane pytania

Źródła i materiały

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