Przelewy24 w WooCommerce: instalacja oficjalnego modułu, klucze, sandbox i zwroty

Oficjalnej wtyczki Przelewy24 nie znajdziesz w katalogu WordPress.org i to pierwsza rzecz, która myli przy podłączaniu bramki. Moduł Przelewy24 dla WooCommerce pobierasz ze strony operatora (zakładka „Do pobrania”, sekcja gotowych wtyczek) i wgrywasz ręcznie jako plik ZIP. W katalogu WordPressa są rozszerzenia innych firm, które też obsługują Przelewy24, ale tutaj opisuję moduł samego operatora, bo do niego odnosi się dokumentacja techniczna i wsparcie Przelewy24.

Operator utrzymuje dwie linie modułu. Starsza jest przeznaczona dla WooCommerce 8.x. Nowa została napisana od zera, pierwsze wydanie ukazało się w lutym 2025 roku, a dokumentacja wskazuje ją dla WooCommerce od wersji 9.x do 11.x. Przed instalacją sprawdź wersję swojego WooCommerce na liście wtyczek, bo ustawienia obu linii wyglądają inaczej. Dalej opisuję nową wersję.

Przelewy24 WooCommerce: instalacja w sześciu krokach

Krok z adresem IP jest najczęściej pomijany, bo nie ma go w samym WordPressie. Na hostingu współdzielonym adres serwera zna tylko dostawca, więc zapytaj go o to przed instalacją. Po przeprowadzce sklepu na inny serwer ten wpis trzeba poprawić, inaczej płatności przestaną działać z dnia na dzień.

Identyfikator sprzedawcy, klucz CRC i klucz API: do czego służą

• Identyfikator sprzedawcy to Twój login do panelu Przelewy24. Znajdziesz go w Moje konto → Weryfikacja konta → Moje sklepy.
• Klucz CRC służy do wyliczania sumy kontrolnej (pola sign) przy rejestracji i weryfikacji każdej transakcji. Przelewy24 liczy ją algorytmem SHA-384, więc jeden zły znak w kluczu psuje każdą płatność.
• Klucz API uwierzytelnia zapytania sklepu do API operatora. W panelu sandboksu bywa opisany jako klucz do raportów. Oba klucze są w Moje konto → Konfiguracja API.

Te trzy wartości dają dostęp do Twoich płatności. Nie przesyłaj ich otwartym tekstem w mailu i nie wklejaj do zgłoszeń na forach. Jeśli podejrzewasz, że wyciekły, skontaktuj się z obsługą Przelewy24 w sprawie ich zmiany i od razu podmień je w sklepie.

Sandbox: płatności bez prawdziwych pieniędzy

Konto testowe zakładasz w panelu w zakładce Moje konto → Konto SANDBOX, a jego dane kopiujesz z osobnego panelu pod adresem sandbox.przelewy24.pl. W module włączasz tryb testowy i wpisujesz klucz CRC oraz klucz API ze środowiska testowego. Klucze produkcyjne przy włączonym trybie testowym nie zadziałają, odwrotnie też nie, a komunikat błędu nie zawsze mówi to wprost.

Na sandboksie przechodzę zawsze te same scenariusze, bo każdy z nich psuje się z innego powodu:

1. 1.Płatność udana: zamówienie musi samo przejść do statusu „W trakcie realizacji”.
2. 2.Płatność przerwana: klient zamyka okno banku, zamówienie zostaje nieopłacone, a towar nie znika ze stanu na zawsze.
3. 3.Zamówienie z kuponem rabatowym i płatną dostawą: kwota w Przelewy24 musi zgadzać się co do grosza z kwotą w sklepie.
4. 4.Zwrot częściowy jednego produktu z zamówienia.

Klient zapłacił, a zamówienie dalej czeka na płatność

Ten objaw ma prawie zawsze tę samą przyczynę: sklep nie odebrał powiadomienia. Po udanej płatności Przelewy24 wysyła powiadomienie na adres podany przy rejestracji transakcji (urlStatus), niezależnie od tego, czy klient wrócił do sklepu. Sklep musi je odebrać i potwierdzić transakcję metodą weryfikacji. Według dokumentacji API dopiero zweryfikowana transakcja jest uznana za potwierdzoną. Bez weryfikacji kwota nie trafia do sprzedawcy, tylko zostaje do dyspozycji klienta jako przedpłata.

Gdy pierwsza próba się nie uda, operator ponawia powiadomienie po 3, 5, 15, 30, 60, 150 i 450 minutach (z tolerancją około 5 minut). Po wyczerpaniu prób sprawę trzeba wyjaśnić ręcznie w panelu. Szukam wtedy przyczyny w tej kolejności:

• Wtyczka bezpieczeństwa lub firewall hostingu odrzuca zapytania z zewnątrz kierowane na adres powiadomień.
• Hasło albo tryb konserwacji na całej stronie, typowe dla kopii testowej: powiadomienie dostaje ekran logowania zamiast sklepu.
• Nowy adres IP serwera po zmianie hostingu, którego nie dopisano w Konfiguracji API.
• Pamięć podręczna obejmująca adresy, które zawsze powinny trafiać do PHP.
• Pomieszane klucze z sandboksu i produkcji, przez które suma kontrolna nie pasuje.

Jeśli płatności wiszą, a nie masz czasu szukać po logach, opisz sytuację w formularzu wyceny. Diagnozę i poprawkę robię jako jednorazowe zlecenie.

Zwroty bez logowania do panelu operatora

Nowy moduł pozwala zlecić zwrot prosto z WooCommerce. W szczegółach zamówienia (WooCommerce → Zamówienia) klikasz „Zwrot” przy produkcie, wpisujesz kwotę i wybierasz „Zwróć przez Przelewy24”. Kwota zwrotu nie może przekroczyć wartości zamówienia ani wolnych środków na Twoim koncie w Przelewy24. Przy większym zwrocie tuż po wypłacie salda operacja może więc zostać odrzucona.

Zwrot pieniędzy to jeszcze nie korekta faktury. Jeśli sklep wystawia faktury firmom, korektę trzeba wystawić osobno, a od 2026 roku trafia ona do KSeF. Jak połączyć to ze sklepem, opisuję w tekście o KSeF w WooCommerce.

BLIK, karta i Apple Pay bez wychodzenia ze sklepu

Moduł potrafi przyjąć kod BLIK na stronie zamówienia, zapamiętać alias BLIK albo kartę zalogowanego klienta (One Click) i pokazać formularz karty, Google Pay oraz Apple Pay bezpośrednio w koszyku. Jest jedno zastrzeżenie: płatność kartą, Google Pay i Apple Pay wewnątrz sklepu wymaga dodatkowej umowy z operatorem kartowym i uruchomienia usług po stronie Przelewy24. Apple Pay potrzebuje do tego jeszcze identyfikatora sprzedawcy i certyfikatu z konta Apple Developer. Zgłoś te metody do operatora wcześniej, bo to osobny proces, niezależny od konfiguracji wtyczki.

Sprzedajesz też w euro? Moduł ma zakładkę Wielowalutowość, w której każda waluta dostaje własne dane dostępowe. Jeśli dopiero wybierasz operatora, różnice między dostawcami opisuję w tekście bramka płatnicza: co to jest, a konfigurację drugiej popularnej bramki w poradniku PayU w WooCommerce.

Źródła: dokumentacja modułów Przelewy24, dokumentacja API Przelewy24.