DataFirefly Subscriptions — Kompletny przewodnik (PrestaShop 8 i 9)
Instalacja, metody płatności (karta, polecenie zapłaty SEPA, PayPal, rozliczenie offline), plany, harmonogram, przypomnienia o płatnościach, strefa klienta i panel administracyjny modułu subskrypcji dla PrestaShop 8 i 9.
Wprowadzenie
DataFirefly Subscriptions pozwala sprzedawać Twoje produkty w subskrypcji w PrestaShop 8 i 9. Tworzysz plany (częstotliwość, rabat, bezpłatny okres próbny, opłata rejestracyjna, zobowiązanie, liczba dostaw); klient wybiera plan na karcie produktu, opłaca pierwsze zamówienie, a następnie każdy termin płatności automatycznie tworzy prawdziwe zamówienie PrestaShop, opłacane automatycznie zapisaną przez klienta metodą płatności (karta, polecenie zapłaty SEPA lub PayPal) albo tworzone jako zamówienie oczekujące na płatność (rozliczenie offline).
- Cena subskrypcji widoczna wszędzie: rabat, bezpłatny okres próbny i opłata rejestracyjna są uwzględniane w koszyku, przy płatności, w zamówieniu i na fakturze.
- Jeden mechanizm rozliczeń: harmonogram sklepu; każda subskrypcja jest rezerwowana przed odnowieniem, dzięki czemu dwa równoczesne uruchomienia nigdy nie obciążą klienta dwukrotnie.
- Klient zarządza wszystkim ze swojego konta: pominięcie dostawy, wstrzymanie, zmiana planu, ilość, adres, metoda płatności, anulowanie.
- Kompletny panel administracyjny: pulpit, lista subskrybentów, karta subskrypcji z osią czasu, edytor planów z podglądem.
Nowości w wersji 3.0.0: polecenie zapłaty SEPA (przez Stripe lub plikiem bankowym pain.008) i PayPal, rozliczenie offline i tryb testowy, opłata rejestracyjna, naprawdę bezpłatny okres próbny, rabat stosowany już od 1. zamówienia, wstrzymanie z automatycznym wznowieniem, zmiana planu i ilości przez klienta, zmiana metody płatności, anulowanie na koniec okresu zobowiązania, przypomnienie przed odnowieniem, grupa klientów „Subskrybenci”, nowy pulpit, e-maile w 8 językach, cron z wiersza poleceń.
Subskrypcja czy zamówienie cykliczne? DataFirefly Subscriptions tworzy zamówienia w terminie płatności i pobiera za nie płatność automatycznie (lub je fakturuje). Jeśli wolisz przed każdym terminem wysyłać klientowi gotowy do opłacenia koszyk, bez automatycznego obciążenia, wybierz raczej moduł DF Recurring Orders.
Instalacja i aktualizacja
- Pobierz plik ZIP ze swojego konta DataFirefly.
- Panel administracyjny: Moduły → Menedżer modułów → Załaduj moduł, wybierz plik ZIP.
- Pojawi się menu Zamówienia → Subskrypcje: Pulpit, Subskrybenci, Plany, Aktywność, Ustawienia, Polecenia zapłaty SEPA.
Wymagania: PrestaShop od 8.0 do 9.x, PHP od 7.4 do 8.5, zadanie zaplanowane (cron) u dostawcy hostingu; w zależności od wybranych metod: konto Stripe (karta, polecenie zapłaty SEPA przez Stripe), konto PayPal Business z dostępem do sejfu PayPal (płatności inicjowane przez sprzedawcę) lub identyfikator wierzyciela (ICS) i bank przyjmujący pliki poleceń zapłaty pain.008. Brak zależności Composer.
Aktualizacja z wersji 2.x: zainstaluj plik ZIP 3.0.0 na istniejącą wersję. Migracja dodaje nowe kolumny, naprawia puste daty zapisane przez wersję 2.x, przypisuje każdej subskrypcji jej sklep, walutę i język, zachowuje Twoje ustawienia (sklep 2.x korzystający ze Stripe zachowuje kartę jako metodę płatności) i usuwa niepotrzebne już pliki. Żadna subskrypcja nie zostaje utracona.
Przy odinstalowaniu subskrypcje są domyślnie zachowywane i odzyskiwane po ponownej instalacji; opcja „Usuń wszystkie dane subskrypcji przy odinstalowaniu modułu” usuwa wszystko.
Wybór metod płatności
Subskrypcje → Ustawienia → Płatność oferuje dwa tryby:
- Zapisana metoda płatności: automatyczne odnowienia — zaznaczasz metody oferowane przy płatności; klient wybiera jedną z nich, zostaje ona zapisana przy 1. zamówieniu, a następnie automatycznie używana przy każdym odnowieniu. Dla koszyka zawierającego subskrypcję oferowane są tylko te metody.
- Rozliczenie offline — 1. zamówienie można opłacić dowolną z Twoich metod płatności (przelew, czek…). Subskrypcja rozpoczyna się, gdy zamówienie otrzyma status opłaconego. Każde odnowienie tworzy zamówienie oczekujące na płatność (domyślnie ze statusem „Oczekiwanie na płatność przelewem”, który wysyła Twoje dane bankowe); klient otrzymuje przypomnienia, a subskrypcja zostaje zawieszona, jeśli zamówienie pozostanie nieopłacone.
Metody dostępne w trybie „Zapisana metoda płatności” (każdy kafelek pokazuje „Gotowe” lub „Do skonfigurowania”):
- Karta (Stripe) — karta zapisana z użyciem 3-D Secure, obciążana przy każdym odnowieniu.
- Polecenie zapłaty SEPA (Stripe) — IBAN jest wpisywany w bezpiecznym formularzu Stripe, który zarządza mandatem. Obciążenie jest potwierdzane przez bank po kilku dniach: zamówienie pozostaje w statusie „Oczekiwanie na polecenie zapłaty SEPA” i przechodzi na „Płatność zaakceptowana”, gdy Stripe je potwierdzi; harmonogram sprawdza wynik, dodatkowy webhook nie jest potrzebny.
- PayPal — klient jednorazowo zatwierdza płatność w PayPal; jego konto zostaje zapisane w sejfie PayPal, a odnowienia są pobierane bez ponownego zatwierdzania. Utwórz aplikację REST w panelu deweloperskim PayPal (najpierw dane dostępowe sandbox, potem produkcyjne); Twoje konto PayPal Business musi mieć uprawnienia do płatności zapisanych („Vault”).
- Polecenie zapłaty SEPA (plik bankowy) — klient podpisuje mandat SEPA w Twoim sklepie (właściciel rachunku, zweryfikowany IBAN, opcjonalny BIC, pole wyboru z podpisem). Obciążenia przekazujesz do banku samodzielnie: zobacz „Polecenia zapłaty SEPA” poniżej. Uzupełnij nazwę wierzyciela, swój identyfikator wierzyciela (ICS) oraz IBAN i BIC rachunku uznawanego.
- Tryb testowy — symulowane karty (testowe numery kart Stripe), bez żadnych rzeczywistych płatności: pozwala przećwiczyć cały cykl przed uruchomieniem produkcyjnym.
Polecenia zapłaty SEPA są oferowane wyłącznie dla koszyków w euro.

Klucze i webhook Stripe
Wpisz klucz publiczny i klucz tajny dla wybranego trybu (testowego lub produkcyjnego); zapisane klucze tajne nigdy nie są ponownie wyświetlane (pozostawienie pustego pola zachowuje dotychczasowy klucz). Następnie utwórz w Stripe webhook kierujący na wyświetlony URL, ze zdarzeniami payment_method.detached, charge.refunded i charge.dispute.created, po czym wklej sekret podpisu whsec_…. Niepodpisane zdarzenia są odrzucane, a każde zdarzenie jest przetwarzane tylko raz.
Tworzenie planu
Subskrypcje → Plany → Nowy plan (lub z zakładki Moduły na karcie produktu):
- Produkt (wyszukiwanie po nazwie, indeksie lub ID) oraz w razie potrzeby jedna kombinacja.
- Odnowienie: tygodniowo, co dwa tygodnie, miesięcznie, kwartalnie, półrocznie lub rocznie, z mnożnikiem („Miesięcznie” co 2 = co 2 miesiące).
- Rabat subskrypcyjny (%): stosowany przy każdej dostawie, po Twoich promocjach katalogowych.
- Opłata rejestracyjna (netto): naliczana jednorazowo wraz z 1. zamówieniem.
- Bezpłatny okres próbny (dni): 1. dostawa jest bezpłatna, pierwsze obciążenie następuje po zakończeniu okresu próbnego.
- Zobowiązanie: liczba opłaconych dostaw, po których można anulować subskrypcję.
- Łączna liczba dostaw: 0 = do anulowania; w przeciwnym razie subskrypcja kończy się samoczynnie (np. 12 numerów).
- Wyświetlanie: nazwa i hasło dla każdego języka, „Najpopularniejszy”, kolejność, aktywacja.
Podgląd po prawej stronie pokazuje kartę planu w takiej postaci, w jakiej się wyświetli. Planu używanego przez subskrypcje nie można usunąć: wyłącz go (trwające subskrypcje są kontynuowane).


Ścieżka klienta
Karta produktu
Blok „Opcje zakupu” porównuje zakup jednorazowy z każdym planem: przekreślona cena, cena za dostawę, oszczędność na dostawie i w skali roku, plakietki (okres próbny, zobowiązanie, opłaty), informacja o 1. zamówieniu. Wybór jest zapamiętywany jeszcze przed pierwszym dodaniem do koszyka.


Koszyk i płatność
Koszyk pokazuje cenę subskrypcji i podsumowanie: plan, okres próbny, opłaty, kwotę cykliczną i datę następnego odnowienia. Przy płatności klient widzi, ile płaci dzisiaj, oraz zgodę na obciążenia przy odnowieniach. Subskrypcja wymaga konta klienta: gość jest proszony o zalogowanie się lub założenie konta.



Polecenia zapłaty SEPA (plik bankowy)
Zamówienia opłacane na podstawie mandatu SEPA oczekują w Subskrypcje → Polecenia zapłaty SEPA:
- zaznacz pobrania, wybierz datę pobrania (z uwzględnieniem terminu wymaganego przez bank) i kliknij Utwórz plik obciążeń;
- pobierz plik XML pain.008 i prześlij go w bankowości internetowej (pierwsze obciążenia FRST i obciążenia cykliczne RCUR są grupowane automatycznie);
- gdy bank zrealizuje płatność, kliknij Oznacz jako opłacone: zamówienia przechodzą na „Płatność zaakceptowana”, subskrypcja się rozpoczyna lub odnowienie zostaje zaliczone;
- odrzucone obciążenie oznacz przyciskiem „Oznacz jako odrzucone”: zamówienie przechodzi na „Błąd płatności”, a subskrypcja podlega Twoim zasadom dotyczącym nieudanych płatności.
Numery IBAN są przechowywane w postaci zaszyfrowanej; wyświetlany jest tylko kraj i 4 ostatnie cyfry. Plik jest generowany od nowa przy każdym pobraniu.

Odnowienia i harmonogram
Harmonogram przetwarza należne odnowienia, ponawia nieudane płatności, wznawia subskrypcje, których wstrzymanie dobiegło końca, śledzi nieopłacone zamówienia offline i trwające polecenia zapłaty SEPA oraz wysyła przypomnienia. Uruchamiaj go raz dziennie (lub co godzinę). Z wiersza poleceń (zalecane; token można też przekazać w zmiennej DFSUBSCRIPTION_CRON_TOKEN):
0 6 * * * php /sciezka/do/sklepu/modules/dfsubscription/cli/run.php --token=TWOJ_TOKEN
lub przez URL: https://twojsklep.pl/module/dfsubscription/cron?token=TWOJ_TOKEN. Kody wyjścia wiersza poleceń: 0 = OK, 2 = nieprawidłowy token, 3 = moduł wyłączony, 5 = nieudane płatności lub błędy. Panel „Harmonogram” w ustawieniach pokazuje ostatnie uruchomienie i pozwala uruchomić harmonogram lub wygenerować nowy token.
Przy każdym odnowieniu: koszyk jest odtwarzany w sklepie, walucie, języku i pod adresem subskrypcji, z pierwotnym przewoźnikiem, jeśli jest dostępny, i z ceną subskrypcji (aktualna cena pomniejszona o rabat lub cena zablokowana, zależnie od ustawień); następnie pobierana jest płatność, tworzone standardowe zamówienie PrestaShop i wysyłany e-mail do klienta. Jeśli produktu brak w magazynie lub jest niedostępny, odnowienie zostaje przełożone o jeden dzień, bez obciążenia i bez liczenia nieudanej próby, a Ty otrzymujesz powiadomienie.
Nieudane płatności i przypomnienia
- Obciążenie się nie powiodło: subskrypcja przechodzi na „Płatność nieudana”, a klient otrzymuje e-mail z linkiem do aktualizacji metody płatności. W przypadku polecenia zapłaty SEPA odrzucone zamówienie przechodzi na „Błąd płatności” i podlega tym samym zasadom.
- Automatyczna ponowna próba po ustawionym czasie (domyślnie 3 próby co 3 dni).
- Po ostatniej próbie: zawieszenie (domyślnie) lub anulowanie, zależnie od ustawień; otrzymujesz powiadomienie.
- Gdy tylko klient zapisze nową metodę płatności, subskrypcja znów staje się aktywna i zostaje obciążona przy następnym uruchomieniu.

Strefa klienta „Moje subskrypcje”
Klient widzi swoje bieżące i zakończone subskrypcje, a dla każdej z nich: status, następną datę, metodę płatności, pozostały okres zobowiązania, dostawy, zamówienia i historię. W zależności od Twoich ustawień może:
- Pominąć następną dostawę.
- Wstrzymać subskrypcję na 1 do N dostaw (automatyczne wznowienie) lub do odwołania, a następnie wznowić ją w zaplanowanym terminie.
- Zmienić plan na inny plan tego produktu (ze skutkiem od następnego odnowienia, bez proporcjonalnego rozliczenia) i zmienić ilość.
- Zmienić adres dostawy i wymienić metodę płatności: nowa karta, nowy IBAN, nowy mandat SEPA lub inne konto PayPal (zmiana obejmuje wszystkie jego subskrypcje opłacane w ten sam sposób).
- Anulować subskrypcję, podając powód; w okresie zobowiązania może jedynie zaplanować anulowanie na koniec okresu zobowiązania (i je wycofać).
Każda akcja jest wysyłana metodą POST z tokenem sesji i sprawdza, czy subskrypcja rzeczywiście należy do klienta.


Panel administracyjny
Pulpit
Szacowany miesięczny przychód cykliczny (netto), aktywni subskrybenci, trwające okresy próbne, wskaźnik rezygnacji z 30 dni, nieudane płatności do obsłużenia, odnowienia w ciągu 7 i 30 dni, obroty z zamówień subskrypcyjnych, przychód na subskrybenta, wykres z 12 miesięcy, nowe subskrypcje i anulowania, podział według statusu, najlepsze plany, nadchodzące odnowienia, ostatnia aktywność i powody anulowania. Dopóki konfiguracja nie jest zakończona, wyświetlany jest przewodnik startowy.

Subskrybenci i karta subskrypcji
Listę można filtrować według statusu (aktywne, okres próbny, wstrzymane, płatność nieudana, oczekujące na płatność, zakończone), eksportować do CSV i wykonywać na niej akcje zbiorcze (wstrzymanie, wznowienie, anulowanie). Karta subskrypcji zawiera wskaźniki, akcje (pobierz płatność lub zafakturuj teraz, pomiń, wstrzymaj, wznów, data następnego odnowienia, plan, ilość, anulowanie, reaktywacja), zamówienia i pełną oś czasu.


Inne ekrany
- Aktywność: wszystkie zdarzenia z filtrowaniem według typu i autora (klient, pracownik, harmonogram).
- Karta zamówienia i karta klienta: panel powiązanych subskrypcji.
- Grupa klientów „Subskrybenci” (Ustawienia): klienci należą do niej, dopóki mają aktywną lub wstrzymaną subskrypcję; wykorzystaj ją do cen specjalnych lub dostępu do kategorii.
E-maile
Wszystkie e-maile są wysyłane w języku klienta (8 języków w zestawie), z kwotami w jego walucie: potwierdzenie subskrypcji, opłacone odnowienie, zlecone polecenie zapłaty SEPA, zamówienie oczekujące na płatność i przypomnienia, nieudana płatność, przypomnienie przed odnowieniem i przed końcem okresu próbnego, wstrzymanie, wznowienie, zmiana, anulowanie, zbliżający się koniec. Sprzedawca otrzymuje powiadomienia o nowych subskrypcjach, anulowaniach, zawieszeniach i przełożonych odnowieniach. Teksty można edytować w Międzynarodowy → Tłumaczenia → Tłumaczenia zainstalowanych modułów.


Najczęstsze pytania i rozwiązywanie problemów
Blok subskrypcji nie pojawia się na karcie produktu
Sprawdź, czy dla tego produktu (lub tej kombinacji) istnieje aktywny plan i czy w ustawieniach co najmniej jedna metoda płatności ma status „Gotowe” (uzupełnione klucze Stripe lub PayPal, kompletne dane wierzyciela SEPA; koszyk w euro w przypadku SEPA).
PayPal odrzuca odnowienia
Sprawdź w PayPal, czy Twoje konto ma uprawnienia do płatności zapisanych (Vault, płatności inicjowane przez sprzedawcę). Błąd zwrócony przez PayPal pojawia się w historii subskrypcji.
Odnowienia nie są realizowane
Panel „Harmonogram” pokazuje ostatnie uruchomienie. Uruchom polecenie ręcznie, aby zobaczyć raport i ewentualne błędy.
Jak bezpiecznie przetestować moduł?
Przełącz się na Tryb testowy, utwórz plan, złóż zamówienie kartą 4242 4242 4242 4242, a następnie użyj przycisku „Pobierz płatność teraz” na karcie subskrypcji. Karta 4000 0000 0000 0341 jest akceptowana przy zamówieniu, a odrzucana przy odnowieniu: idealna do testowania przypomnień.
Potrzebujesz pomocy? Otwórz zgłoszenie ze swojego konta DataFirefly: odpowiedź w ciągu 24 godzin roboczych, po francusku lub po angielsku.