PayNow for WooCommerce

Wymagania: WordPress 6.4 lub nowszy, WooCommerce 8.3 lub nowszy, PHP 7.4 lub nowszy.
Waluta sklepu: PLN, EUR, GBP lub CZK.

1. Czym jest wtyczka

PayNow for WooCommerce integruje bramkę płatności Paynow (mBank / mElements S.A.) ze sklepem WooCommerce.
Udostępnia sześć metod płatności jako osobne bramki WooCommerce:

Metoda	Jak działa dla klienta
PayNow — szybki przelew	wybór banku na stronie płatności Paynow (pay-by-link)
BLIK	kod 6-cyfrowy wpisywany bezpośrednio w kasie sklepu, potwierdzenie w aplikacji banku
PayPo	płatność odroczona „kup teraz, zapłać później”
Karta płatnicza	Visa/Mastercard z 3D Secure
Apple Pay	widoczna tylko na urządzeniach Apple z aktywnym Apple Pay
Google Pay	widoczna w Chrome i na Androidzie

Wtyczka obsługuje klasyczny checkout (shortcode) i nowy Block Checkout, HPOS (High-Performance Order Storage),
zwroty z poziomu zamówienia, automatyczną aktualizację statusów (webhooki + zapasowe odpytywanie API)
oraz ponawianie nieudanych płatności.

2. Instalacja

• Wtyczki → Dodaj nową → Wgraj wtyczkę → wybierz plik ZIP → Zainstaluj → Aktywuj.
• Wtyczka wymaga aktywnego WooCommerce — bez niego wyświetli komunikat i nie uruchomi bramek.

3. Konfiguracja krok po kroku

3.1. Klucze API

• Zaloguj się do panelu Merchanta Paynow (produkcja: panel.paynow.pl, testy: panel.sandbox.paynow.pl).
• Przejdź do Ustawienia → Sklepy i punkty płatności → Dane uwierzytelniające i skopiuj Klucz dostępu do API
  oraz Klucz obliczania podpisu.
• W WordPressie: WooCommerce → Ustawienia → PayNow → wklej klucze w pola odpowiedniego środowiska.
• Pole „Tryb sandbox” przełącza między środowiskiem testowym a produkcyjnym.

Bezpieczeństwo: zapisane klucze nie są nigdy wyświetlane w formularzu (pole pokazuje „•••• zapisany”).
Pusty zapis zachowuje istniejący klucz.

3.2. Test połączenia i automatyczna konfiguracja

Kliknij przycisk Testuj połączenie z PayNow. Wtyczka:

• zweryfikuje klucze wobec API Paynow,
• pobierze listę dostępnych metod płatności,
• automatycznie zapisze identyfikatory metod (paymentMethodId) dla BLIK, PayPo, Karty, Apple Pay i Google Pay
  w ustawieniach odpowiednich bramek.

Wynik zobaczysz w zielonym (lub czerwonym) pasku u góry strony.

3.3. Adres powiadomień (webhook) — wymagane

W panelu Merchanta Paynow (Ustawienia → Sklepy i punkty płatności → Adres powiadomień) ustaw:

https://twoja-domena.pl/wp-json/paynow/v1/notification

Dokładny adres dla Twojego sklepu wtyczka wyświetla w nagłówku swoich ustawień. Bez tego statusy zamówień nie będą
aktualizować się natychmiast (zadziała wolniejszy mechanizm zapasowy — patrz punkt 5.3).

Uwaga: „Adres powiadomień” to inne pole niż „Adres powrotu”. Adres powrotu może pozostać pusty — wtyczka
przekazuje własny adres powrotu przy każdej płatności.

3.4. Włączenie bramek

WooCommerce → Ustawienia → Płatności → włącz wybrane bramki PayNow przełącznikami. Każda bramka ma własne
ustawienia (tytuł, opis, paymentMethodId) pod przyciskiem „Zarządzaj”.

4. Metody płatności i ich aktywacja

Część metod wymaga aktywacji po stronie Paynow, zanim zaczną działać:

Metoda	Co trzeba zrobić po stronie Paynow
PayNow (przelewy)	nic — aktywna od razu
BLIK (kod w kasie)	aktywacja White Label: wyświetl klauzulę RODO Paynow w sklepie, wyślij zrzut ekranu i link do sklepu na support@paynow.pl
PayPo	Ustawienia → Sklepy i punkty płatności → Aktywuj PayPo w panelu (wymaga licencji mElements)
Karta	wniosek: Metody płatności → Płatność kartą → Aktywuj (wymaga licencji mElements)
Google Pay	wniosek po pozytywnym rozpatrzeniu wniosku kartowego
Apple Pay	wniosek po wniosku kartowym (operator Worldline); weryfikacja Apple trwa 2–5 dni

Jeśli Twoje konto Paynow działa na starszej licencji mBank, panel poprowadzi Cię przez bezpłatną zmianę licencji
na mElements (proces online, bramka działa bez przerwy). Dopóki metoda nie jest aktywna w panelu — wyłącz jej bramkę
w WooCommerce, żeby klienci jej nie widzieli.

PayPo — wymagania szczególne

PayPo wymaga pełnego adresu kupującego (ulica z numerem, kod pocztowy, miasto, kraj). Wtyczka pilnuje tego przed
wysłaniem płatności i wskazuje brakujące pola. Adres „Krowia 45″ jest automatycznie rozdzielany na ulicę i numer domu
zgodnie z wymogami API.

Tryb pracy PayPo (w ustawieniach bramki): Paywall (domyślny — klient wybiera PayPo na stronie Paynow) lub White Label
(bezpośrednio do PayPo; wymaga dodatkowej aktywacji przez support Paynow).

5. Przebieg płatności

5.1. Ścieżka pozytywna

• Klient wybiera metodę w kasie i klika „Kupuję i płacę”.
• Przelewy, karta i portfele: przekierowanie na stronę płatności Paynow → autoryzacja → powrót na stronę
  „Zamówienie otrzymane”. BLIK: klient trafia od razu na stronę „Zamówienie otrzymane” i potwierdza płatność
  w aplikacji banku.
• Strona podziękowań pokazuje status na żywo („oczekujemy na potwierdzenie” z automatycznym odświeżaniem), a po zaksięgowaniu — standardowe potwierdzenie WooCommerce.
• Zamówienie zmienia status na Przetwarzanie (lub Zakończone dla produktów wirtualnych).

5.2. Ścieżka negatywna (odrzucenie lub błąd)

Zamówienie dostaje status Nieudane, a klient widzi na stronie podziękowań komunikat o braku płatności i przycisk
Zapłać za zamówienie. Ponowna płatność jest powiązana z tym samym zamówieniem (mechanizm ABANDONED w Paynow).
Link do ponowienia płatności jest też w mailu WooCommerce i w Moje konto → Zamówienia.

5.3. Aktualizacja statusów

Statusy przychodzą dwiema drogami:

• Webhook (natychmiast) — Paynow wysyła powiadomienie na adres z punktu 3.3; wtyczka weryfikuje podpis HMAC-SHA256
  i odrzuca sfałszowane żądania. Duplikaty powiadomień są ignorowane.
• Odpytanie API (zapasowo) — przy każdym wejściu na stronę podziękowań zamówienia oczekującego wtyczka sprawdza status
  bezpośrednio w API Paynow.

6. Zwroty

• Otwórz opłacone zamówienie → Pozycje zamówienia → Zwrot.
• Wpisz kwotę (możliwe zwroty częściowe i wielokrotne — do łącznej kwoty zamówienia).
• Kliknij Zwrot przez PayNow (nie „Zwrot ręczny” — ten nie przelewa pieniędzy!).
• Wtyczka zapisze refundId i status w notatce zamówienia; środki wracają do klienta zwykle do 24 godzin.

Wymagania: zamówienie opłacone (Przetwarzanie/Zakończone), harmonogram wypłat „dziennie” w panelu Paynow,
minimalna kwota 0,01 zł (1 zł dla płatności kartą). Powód zwrotu wpisany w WooCommerce trafia do notatki zamówienia
(API Paynow nie przyjmuje własnych opisów).

7. Statusy zamówień

8. Narzędzia administratora

• Kolumna „PayNow” na liście zamówień — kolorowy status płatności (zielony CONFIRMED, żółty PENDING, czerwony REJECTED).
• paymentId i refundId w edycji zamówienia (sekcja płatności) + link do panelu Merchanta.
• Widget kokpitu — 10 ostatnich transakcji PayNow z linkami.
• Logi: włącz „Logowanie debug” w ustawieniach → WooCommerce → Status → Logi → źródło „paynow”.
  Klucze API i kody BLIK są maskowane, adresy e-mail klientów anonimizowane (RODO).
• Filtry dla developerów: paynow_wc_payment_payload (modyfikacja żądania płatności), paynow_wc_payment_amount (modyfikacja kwoty).

9. Rozwiązywanie problemów

Objaw	Przyczyna i rozwiązanie
„Requests signature verification failed”	Błędny lub niepełny klucz podpisu; klucz z innego środowiska (sandbox/produkcja). Wklej klucze ponownie i użyj „Testuj połączenie”.
Zamówienie nie zmienia statusu	Brak adresu powiadomień w panelu Paynow (punkt 3.3). Sprawdź logi — powinny być wpisy „Webhook received”.
„Payment method is not available”	Metoda nieaktywna w panelu Paynow (punkt 4) — złóż wniosek lub wyłącz bramkę.
„PayPo wymaga: …” w kasie	Klient nie uzupełnił wskazanych pól adresu — to poprawna walidacja.
BLIK pyta o kod drugi raz na stronie Paynow	Brak paymentMethodId (kliknij „Testuj połączenie”) lub brak aktywacji White Label.
„invalid field value” przy zwrocie	Zaktualizuj wtyczkę do wersji 0.2.7 lub nowszej.
Klient wrócił przed zaksięgowaniem	Normalne — strona podziękowań odświeża się automatycznie do 2 minut, a status doślą webhook lub API.