Opłaty za Płatność (dfpaymentfees) — Kompletny przewodnik

Wprowadzenie

DataFirefly Opłaty za Płatność pozwala naliczać dodatkowe opłaty do każdej metody płatności w Twoim sklepie PrestaShop 8 lub 9. Cel jest dwojaki: przenieść rzeczywisty koszt danej formy płatności (prowizje od kart, obsługa pobrania, przetwarzanie czeków lub przelewów) oraz skierować klientów do metod płatności najkorzystniejszych dla Twojego sklepu.

Moduł opiera się na silniku reguł: każda reguła łączy kwotę stałą i/lub procent, podstawę naliczania, limity, próg bezpłatności oraz zestaw warunków (grupa klientów, kraj, waluta, wartość koszyka). Opłaty są pokazywane klientowi podczas checkoutu, a następnie dodawane automatycznie do zamówienia przy jego zatwierdzeniu.

Instalacja

1. W zapleczu PrestaShop przejdź do Moduły → Menedżer modułów → Wgraj moduł.
2. Wybierz plik dfpaymentfees.zip pobrany z Twojego konta DataFirefly.
3. Kliknij Zainstaluj, a następnie Konfiguruj.
4. Wyczyść pamięć podręczną PrestaShop (Parametry zaawansowane → Wydajność → Wyczyść pamięć podręczną).
5. Na stronie konfiguracji kliknij Zarządzaj regułami opłat, aby utworzyć pierwszą regułę.

Ustawienia ogólne

Strona konfiguracji modułu (Moduły → Menedżer modułów → Opłaty za Płatność → Konfiguruj) zawiera dwa ustawienia globalne:

• Pokazuj opłaty w checkoucie — wyświetla kwotę opłaty obok każdej metody płatności podczas składania zamówienia. Wyłącz tę opcję, jeśli wolisz naliczać opłaty dopiero przy zatwierdzeniu, bez zapowiadania ich na liście metod płatności.
• Etykieta opłaty — domyślna etykieta pokazywana klientowi i w zamówieniu (na przykład „Opłata za płatność”). Pole jest wielojęzyczne i może być nadpisane w każdej regule.

Tworzenie reguły opłaty

W widoku Zarządzaj regułami opłat kliknij Dodaj regułę opłaty. Formularz jest podzielony na cztery bloki: identyfikacja, kwota, limity i warunki.

Identyfikacja

• Aktywna — włącza lub wyłącza regułę bez jej usuwania.
• Etykieta (klient) — tekst pokazywany klientowi w checkoucie i w zamówieniu. Pole wielojęzyczne i wymagane.
• Metoda płatności — docelowy moduł (na przykład ps_wirepayment, ps_checkpayment, Twój moduł kart płatniczych…) lub Wszystkie metody płatności dla reguły ogólnej.
• Priorytet — liczba całkowita. Niższa wartość jest oceniana jako pierwsza. Zobacz „Kolejność oceny reguł” poniżej.

Kwota opłaty

• Opłata stała — dodawana kwota stała (na przykład 1.50).
• Opłata procentowa — procent naliczany od podstawy (na przykład 2.5 dla 2,5 %).
• Uwzględnij koszty wysyłki w podstawie % — jeśli włączone, procent dotyczy produktów i kosztów wysyłki; w przeciwnym razie tylko produktów.
• Podstawa naliczania brutto — wybierz, czy procent liczony jest od sumy brutto czy netto.

Obie kwoty można łączyć. Stosowany wzór:

opłata = opłata_stała + (podstawa × opłata_procentowa / 100)

Limity i bezpłatność

• Opłata minimalna — jeśli wyliczenie da niższą kwotę, stosowane jest to minimum. 0 = brak minimum.
• Opłata maksymalna — ogranicza kwotę opłaty. 0 = brak maksimum.
• Próg bezpłatności — jeśli wartość brutto koszyka osiągnie tę kwotę, opłata nie jest naliczana. 0 = wyłączone.

Warunki stosowania

Cztery rodziny warunków pozwalają precyzyjnie określić, kiedy reguła obowiązuje. Pusta lista oznacza „brak ograniczeń” dla danego kryterium.

• Grupy klientów — reguła obowiązuje tylko wtedy, gdy klient należy do jednej z wybranych grup. Typowo: naliczać opłaty klientom indywidualnym i zwolnić firmy.
• Kraje — na podstawie kraju adresu rozliczeniowego koszyka.
• Waluty — reguła obowiązuje tylko dla wybranych walut.
• Minimalna / maksymalna wartość koszyka — reguła obowiązuje tylko wtedy, gdy wartość brutto koszyka mieści się w tym przedziale. 0 wyłącza odpowiednią granicę.

W trybie multisklep dodatkowe pole Sklepy pozwala przypisać regułę do jednego lub kilku sklepów. Pozostawienie pustego pola przypisuje regułę do wszystkich sklepów.

Kolejność oceny reguł

Dla danej metody płatności moduł pobiera wszystkie aktywne reguły dotyczące tego modułu (lub „Wszystkich”), posortowane rosnąco według priorytetu, a następnie według identyfikatora. Ocenia warunki każdej reguły w tej kolejności i stosuje pierwszą regułę, której wszystkie warunki są spełnione. Kolejne reguły są pomijane.

Szczególny przypadek progu bezpłatności: jeśli reguła pasuje, ale koszyk osiąga jej próg bezpłatności, żadna opłata nie jest naliczana — a moduł nie ocenia kolejnych reguł. Zniesienie opłaty jest zatem decyzją ostateczną, a nie zwykłym „przejściem do następnej reguły”.

Obsługa VAT

Dwa ustawienia decydują o traktowaniu podatkowym opłat:

• Kwoty wprowadzone brutto — wskaż, czy wprowadzone przez Ciebie kwoty (opłata stała, limity) zawierają już VAT.
• Reguła podatkowa — reguła podatkowa PrestaShop stosowana do opłaty. Wybierz Brak podatku dla opłat bez VAT.

Moduł wylicza obowiązującą stawkę na podstawie reguły podatkowej i adresu rozliczeniowego klienta, a następnie wyprowadza rozbicie:

• Przy kwotach brutto: netto = brutto / (1 + stawka).
• Przy kwotach netto: brutto = netto × (1 + stawka).

Obie wartości wraz z zastosowaną stawką są zapisywane w zamówieniu na potrzeby księgowości.

Przykład obliczenia

Reguła: opłata stała 5,00 zł + 2 % koszyka, podstawa brutto produkty + wysyłka, limit maksymalny 25,00 zł, kwoty wprowadzone brutto, VAT 23 %.

• Koszyk: 600,00 zł brutto produktów + 20,00 zł brutto wysyłki = podstawa 620,00 zł.
• Opłata brutto: 5,00 + (620,00 × 2 / 100) = 17,40 zł brutto.
• Poniżej limitu 25,00 zł: pozostaje bez zmian.
• Rozbicie: netto = 17,40 / 1,23 = 14,15 zł, VAT = 3,25 zł.

Prezentacja po stronie klienta

Gdy opcja Pokazuj opłaty w checkoucie jest włączona, moduł wylicza opłatę dla każdej dostępnej metody płatności i przekazuje ją do front office. Na stronie /order:

• Kwota opłaty jest dopisywana obok etykiety każdej objętej nią metody płatności.
• Pod listą metod płatności pojawia się przypomnienie dla aktualnie wybranej opcji, aktualizowane w czasie rzeczywistym przy zmianie metody płatności.

Prezentacja ma charakter wyłącznie informacyjny: kwota faktycznie naliczona jest przeliczana po stronie serwera przy zatwierdzeniu zamówienia.

Naliczenie w zamówieniu

Przy zatwierdzeniu zamówienia (hook actionValidateOrder) moduł ponownie wylicza opłatę dla faktycznie użytej metody płatności, a następnie:

1. Aktualizuje sumy zamówienia (total_paid, total_paid_tax_incl, total_paid_tax_excl oraz w stosownych przypadkach total_paid_real).
2. Aktualizuje sumy faktury, jeśli faktura już istnieje.
3. Aktualizuje zapisaną kwotę płatności, aby zachować zgodność z kwotą pobraną.
4. Zapisuje wiersz opłaty (etykieta, netto, brutto, stawka) w tabeli df_payment_fee_order.

Wiersz opłaty jest następnie pokazywany na stronie potwierdzenia zamówienia, w szczegółach zamówienia po stronie klienta, na stronie zamówienia w zapleczu oraz dołączany do e-maila potwierdzającego.

Zabezpieczenie zapobiega podwójnemu przetwarzaniu: jeśli zamówienie ma już wiersz opłaty, moduł nie podejmuje żadnych działań.

Zgodność z bramkami płatniczymi

• Płatności offline (przelew, czek, pobranie, płatność w sklepie): działanie jest pełne i bez zastrzeżeń. Klient widzi opłatę, zamówienie i faktura ją zawierają, a Ty pobierasz pokazaną sumę całkowitą.
• Bramki z przekierowaniem lub osadzone (PayPal, Stripe, rozwiązania bankowe): kwota przekazana do bramki jest kwotą wyliczoną przez moduł płatności na podstawie koszyka. W zależności od bramki i jej konfiguracji kwota ta może nie zawierać opłaty. Sprawdź zachowanie w środowisku testowym przed wdrożeniem produkcyjnym.

W tym drugim przypadku typowe są dwa podejścia: ograniczyć reguły opłat do metod płatności offline albo przechwycić lub skorygować kwotę po stronie bramki. Nasze wsparcie doradzi w zależności od używanej bramki.

Multisklep i wielojęzyczność

Multisklep — każda reguła jest przypisana do jednego lub kilku sklepów przez pole Sklepy w formularzu. Oceniane są wyłącznie reguły przypisane do bieżącego sklepu. Reguła zapisana bez wyboru jest przypisana do wszystkich sklepów.

Wielojęzyczność — etykieta każdej reguły jest tłumaczona na wszystkie aktywne języki sklepu. Jeśli etykieta nie została wypełniona w języku klienta, moduł używa globalnej etykiety zdefiniowanej w ustawieniach modułu.

Rozwiązywanie problemów

Opłaty nie pojawiają się w checkoucie

• Sprawdź, czy opcja Pokazuj opłaty w checkoucie jest włączona w ustawieniach modułu.
• Sprawdź, czy reguła jest aktywna i czy dotyczy właściwej metody płatności (lub „Wszystkich”).
• Sprawdź, czy kontekst klienta spełnia wszystkie warunki: grupa, kraj rozliczeniowy, waluta, wartość koszyka.
• Upewnij się, że koszyk nie osiąga progu bezpłatności reguły.
• Wyczyść pamięć podręczną PrestaShop i wymuś przeładowanie przeglądarki (Ctrl+F5), aby usunąć stary JavaScript.

Opłaty są pokazywane, ale nie są dodawane do zamówienia

Obliczenie w checkoucie i przy zatwierdzeniu korzysta z technicznej nazwy modułu płatności. Jeśli Twój moduł płatności zapisuje etykietę inną niż nazwa techniczna, sprawdź w tabeli df_payment_fee_order, czy dla zamówienia powstał wiersz. Jeśli nie, utwórz regułę obejmującą Wszystkie metody płatności, aby zweryfikować działanie, a następnie skontaktuj się ze wsparciem, podając nazwę używanego modułu płatności.

Reguła nigdy nie obowiązuje, choć wygląda poprawnie

Prawdopodobnie wcześniej dopasowuje się reguła o wyższym priorytecie (niższej wartości priorytetu). Pamiętaj, że stosowana jest tylko pierwsza pasująca reguła. Zwiększ wartość priorytetu reguł ogólnych lub doprecyzuj warunki reguł konkurencyjnych.

Kwota VAT wydaje się nieprawidłowa

Sprawdź spójność między ustawieniem Kwoty wprowadzone brutto a wpisanymi wartościami. Kwota wprowadzona brutto przy ustawieniu wskazującym netto (lub odwrotnie) przesuwa rozbicie. Sprawdź również, czy wybrana reguła podatkowa obowiązuje dla kraju rozliczeniowego klienta.

Checkout działa wolno lub się zawiesza

Upewnij się, że używasz wersji modułu 1.0.0 lub nowszej, wyczyść pamięć podręczną PrestaShop i wymuś przeładowanie przeglądarki (Ctrl+F5), aby usunąć zbuforowaną wersję JavaScript.

Deinstalacja

Odinstaluj moduł z poziomu Menedżera modułów. Deinstalacja usuwa zakładkę administracyjną, zmienne konfiguracyjne oraz wszystkie tabele modułu, w tym historię opłat naliczonych do zamówień. Sumy już zapisane w istniejących zamówieniach pozostają niezmienione.