# PayPo dla Magento 2 Moduł dodaje do sklepu na Magento 2 / Adobe Commerce płatność **PayPo — kup teraz, zapłać później**. Klient kończy zamówienie w sklepie, potwierdza płatność po stronie PayPo i wraca na stronę podziękowania. Sklep dostaje pieniądze od PayPo, a klient rozlicza się z PayPo (30 dni lub raty). **Wersja: 2.0.0** · Magento 2.4.6 – 2.4.8 · PHP 8.2 / 8.3 / 8.4 --- ## Co to daje sklepowi | | | |---|---| | **Wyższa konwersja** | Klient nie musi mieć środków w chwili zakupu — typowo najmocniej działa w koszykach o wyższej wartości. | | **Zero ryzyka po stronie sklepu** | Rozliczenie i windykacja są po stronie PayPo. | | **Pełna automatyka** | Faktura, potwierdzenie transakcji i anulowanie nieopłaconych zamówień dzieją się bez pracy obsługi. | | **Zwroty z panelu Magento** | Memo zwrotne w Magento uruchamia zwrot w PayPo — bez logowania do panelu PayPo. | | **Kontrola widoczności** | Metodę można ograniczyć progiem wartości koszyka, listą krajów i widokiem sklepu. | ## Wymagania * Magento Open Source lub Adobe Commerce **2.4.6 – 2.4.8** * PHP **8.2, 8.3 lub 8.4** * Umowa z PayPo oraz dane dostępowe do API (Merchant ID + API Secret, osobne dla sandboxa i produkcji) * Sklep osiągalny publicznie po HTTPS — PayPo wysyła powiadomienia o płatności na adres sklepu ## Instalacja Przez Composer (zalecane): ```bash composer require paypo/module-payment bin/magento module:enable PayPo_Payment bin/magento setup:upgrade bin/magento setup:di:compile bin/magento setup:static-content:deploy pl_PL bin/magento cache:flush ``` Albo ręcznie — zawartość `app/code/PayPo/Payment` skopiować do `app/code/PayPo/Payment` w sklepie i wykonać te same komendy od `module:enable`. ## Konfiguracja **Sklepy → Konfiguracja → Sprzedaż → Metody płatności → PayPo** | Ustawienie | Znaczenie biznesowe | |---|---| | Włączone | Czy PayPo jest widoczne w koszyku. | | Tytuł | Nazwa metody pokazywana klientowi. | | Tryb testowy (sandbox) | Przełącznik między środowiskiem testowym a produkcyjnym PayPo. | | Adres API / Merchant ID / Klucz API | Dane z umowy z PayPo, osobno dla sandboxa i produkcji. | | Typ produktu | `CORE` — płatność odroczona (4 raty, wartość narzucona przez PayPo). `PNX` — raty, liczbę rat ustala sklep. | | Status nowego zamówienia | Status nadawany zamówieniu zaraz po jego złożeniu, zanim klient zapłaci. | | Anuluj po nieudanej płatności | Automatycznie anuluje zamówienie, gdy klient przerwie lub PayPo odrzuci płatność. Zwalnia stan magazynowy. | | Automatyczna faktura | Wystawia fakturę w Magento od razu po zaakceptowaniu płatności przez PayPo. | | Potwierdzenie po wystawieniu faktury | Decyduje, kiedy sklep potwierdza transakcję w PayPo: **Tak** — przy fakturze, **Nie** (domyślnie) — przy wysyłce. | | Minimalna wartość zamówienia | Poniżej tej kwoty PayPo nie jest pokazywane. `0` wyłącza limit. | | Logo, Instrukcje | Grafika i tekst przy metodzie płatności w koszyku. | | Płatność z wybranych krajów, Kolejność | Standardowe ustawienia Magento. | Ustawienia można różnicować per widok sklepu — np. inny próg minimalnej wartości zamówienia albo inne dane API dla poszczególnych rynków. ## Jak wygląda proces 1. Klient wybiera PayPo w koszyku i klika „Złóż zamówienie”. 2. Zamówienie powstaje w Magento ze statusem z ustawienia *Status nowego zamówienia*. 3. Klient trafia na stronę PayPo i potwierdza tam płatność. 4. PayPo wysyła do sklepu powiadomienie o wyniku: * **zaakceptowana** → (opcjonalnie) faktura i płatność w Magento, * **odrzucona / anulowana** → (opcjonalnie) anulowanie zamówienia, * **oczekująca** → zamówienie czeka na ostateczną decyzję. 5. Klient wraca do sklepu — na stronę podziękowania albo do koszyka z zachowaną zawartością. 6. Sklep potwierdza transakcję w PayPo przy wysyłce lub przy fakturze — zależnie od konfiguracji. 7. Zwrot: memo zwrotne w Magento zleca zwrot w PayPo, także częściowy. Powiadomienie z PayPo jest weryfikowane przed jakąkolwiek zmianą zamówienia: sprawdzany jest Merchant ID, kwota zamówienia oraz identyfikator transakcji założonej przez sklep. Payload, który się nie zgadza, jest odrzucany i zapisywany w logu. ## Diagnostyka Wszystkie zdarzenia i błędy komunikacji z PayPo trafiają do `var/log/paypo.log` (dane wrażliwe, w tym klucz API, nie są logowane). Najczęstsze przyczyny problemów: * PayPo nie widać w koszyku → metoda wyłączona, koszyk poniżej progu minimalnego albo kraj spoza listy. * Klient wraca do koszyka zamiast na stronę PayPo → błąd zakładania transakcji, szczegóły w `paypo.log`. * Zamówienia zostają w statusie oczekującym → sprawdzić, czy adres sklepu jest publicznie dostępny po HTTPS (PayPo musi dosłać powiadomienie). --- ## Changelog ### 2.0.0 Wydanie utrzymaniowe pod najnowsze Magento i PHP. Dla sklepu oznacza to przede wszystkim: możliwość aktualizacji platformy bez blokera po stronie płatności, mniej „cichych” błędów i szczelniejszą weryfikację powiadomień o płatności. **Zgodność** * Pełne wsparcie **Magento 2.4.8** i **PHP 8.4** (moduł działa też na PHP 8.2 i 8.3). * Usunięto konstrukcje wycofane przez Magento i PHP, które w nowszych wersjach kończyły się błędem lub ostrzeżeniem w logach. * Dodany `composer.json` — moduł można instalować i aktualizować Composerem jak każde inne rozszerzenie. **Bezpieczeństwo** * Klucz API przestał trafiać do logu przy nieudanym logowaniu do API PayPo. * Endpoint powiadomień przestał wyłączać ochronę CSRF w całym sklepie — wyjątek dotyczy teraz wyłącznie samego adresu powiadomień PayPo. * Powiadomienie jest odrzucane, jeśli nie zgadza się Merchant ID sklepu, kwota zamówienia lub metoda płatności zamówienia. * Adres przekierowania do PayPo jest walidowany przed użyciem. **Stabilność i poprawki** * Brak odpowiedzi lub błąd po stronie PayPo kończy się czytelnym komunikatem dla klienta zamiast błędu 500 — dodano limity czasu połączenia (10 s) i całego żądania (30 s). * Poprawiono anulowanie i zwrot zamówienia, dla którego nie udało się odnaleźć transakcji PayPo — wcześniej kończyło się to błędem krytycznym. * Poprawiono przekierowanie na stronę płatności: adres nie jest już zniekształcany przy zapisie, a link działa również w sklepach z kodem języka w adresie URL i wielodomenowych. * Konfiguracja PayPo jest czytana zawsze w kontekście widoku sklepu, z którego pochodzi zamówienie — w sklepach wielojęzycznych / wielodomenowych nie ma już ryzyka użycia danych API innego sklepu. * Błędy potwierdzenia transakcji przy fakturze i wysyłce nie są już pomijane po cichu — trafiają do `var/log/paypo.log`. * Próg *Minimalna wartość zamówienia* jest sprawdzany na bieżącym koszyku, a nie na wartości odczytanej przy starcie sesji. * Uzupełnione i poprawione tłumaczenia polskie (część etykiet i komunikatów wcześniej nie tłumaczyła się z powodu literówek). **Uwagi migracyjne** * Zamówienia złożone na starszych wersjach modułu działają dalej — link do płatności zapisany w starym formacie jest nadal obsługiwany. * Usunięto plugin globalnie wyłączający walidację CSRF (`PayPo\Payment\Plugin\CsrfValidatorSkip`). Jeśli był nadpisywany lub używany przez inny moduł, wymaga to sprawdzenia. * Metody API modułu mają teraz jawne typy argumentów i zwracanych wartości; integracje własne rozszerzające moduł należy przetestować przed wdrożeniem. * Po aktualizacji: `bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush`. ### 1.3.0 i wcześniejsze Wersje utrzymywane pod Magento 2.2 – 2.4.7 i PHP do 8.2 włącznie.