DataFirefly Subscriptions — Kompletny przewodnik (PrestaShop 8 i 9)

Prezentacja

DataFirefly Subscriptions zamienia Twój sklep PrestaShop 8 lub 9 w maszynę do przychodów cyklicznych. Moduł opiera się na architekturze „card on file”: klient płaci raz przy checkoutcie przez natywną opcję płatności, jego karta jest bezpiecznie zapisywana w Stripe, a codzienny cron automatycznie obciąża kartę przy każdym terminie i tworzy prawdziwe zamówienie PrestaShop na dokładną kwotę, z kosztami wysyłki włącznie.

Kluczowe punkty architektury:

• Jeden silnik rozliczeń — żadnego obiektu Subscription po stronie Stripe, wszystkim steruje Twój sklep. Podwójne obciążenia są strukturalnie niemożliwe.
• Dokładne kwoty — każde odnowienie odbudowuje realny koszyk i liczy sumę silnikiem cen PrestaShop (rabaty, podatki, wysyłka).
• 3DS/SCA obsłużone — silne uwierzytelnianie odbywa się przy płatności początkowej; odnowienia używają zgodnego z SCA mechanizmu off-session.
• Żadnych danych bankowych po stronie PrestaShop — zgodność PCI-DSS zapewnia Stripe.

Instalacja

1. Pobierz ZIP modułu ze swojego konta klienta DataFirefly.
2. W back-office PrestaShop: Moduły → Menedżer modułów → Zainstaluj moduł, następnie wybierz ZIP.
3. Moduł automatycznie tworzy tabele, zakładki administracyjne (Subskrypcje, Plany, Logi, Dashboard) i rejestruje hooki.
4. Kliknij Konfiguruj, aby otworzyć stronę konfiguracji.

Konfiguracja Stripe

Klucze API

W konfiguracji modułu podaj klucze Stripe. Moduł obsługuje dwa oddzielne zestawy kluczy:

• Tryb testowy: klucz publiczny pk_test_... i klucz sekretny sk_test_... — do walidacji pełnej ścieżki bez realnego obciążenia (karta testowa 4242 4242 4242 4242).
• Tryb live: klucz publiczny pk_live_... i klucz sekretny sk_live_... — do produkcji.

Klucze znajdziesz w dashboardzie Stripe: Developers → API keys. Przełączaj się między test a live przełącznikiem „Tryb” w module.

Webhook

Webhook służy wyłącznie zdarzeniom wyjątkowym (rozliczeniami steruje cron, nie Stripe). W dashboardzie Stripe: Developers → Webhooks → Add endpoint, z URL wyświetlanym w konfiguracji modułu (postaci https://twojsklep.pl/module/dfsubscription/webhook), i zasubskrybuj te trzy zdarzenia:

• payment_method.detached — karta usunięta po stronie Stripe: subskrypcja przechodzi w stan „płatność nieudana”, aby ostrzec Cię przed terminem.
• charge.dispute.created — spór (chargeback): logowany na danej subskrypcji.
• charge.refunded — zwrot: logowany na danej subskrypcji.

Następnie skopiuj sekret podpisu (whsec_...) dostarczony przez Stripe do odpowiedniego pola konfiguracji.

Konfiguracja crona

Cron jest silnikiem odnowień: codziennie wykrywa subskrypcje z upływającym terminem, obciąża zapisane karty i tworzy zamówienia. Zabezpieczony tokenem URL jest wyświetlany w konfiguracji i dashboardzie modułu, w postaci:

https://twojsklep.pl/module/dfsubscription/cron?token=TWOJ_TOKEN

Utwórz codzienne zadanie cron u hostingodawcy (cPanel, Plesk, crontab) wywołujące ten URL. Przykład crontab dla wykonania codziennie o 6:00:

0 6 * * * curl -s "https://twojsklep.pl/module/dfsubscription/cron?token=TWOJ_TOKEN" > /dev/null 2>&1

Tworzenie planów subskrypcji

Plany zarządza się bezpośrednio z karty produktu w back-office: Katalog → Produkty → Twój produkt → zakładka Moduły / DataFirefly Subscriptions. Dla każdego planu zdefiniuj:

• Częstotliwość rozliczeń — tygodniowa, dwutygodniowa, miesięczna, kwartalna, półroczna lub roczna.
• Częstotliwość dostaw — identyczna z rozliczeniami, tygodniowa, dwutygodniowa lub miesięczna. Przykład: rozliczenie miesięczne + dostawa tygodniowa = cotygodniowy box z płatnością miesięczną.
• Rabat (%) — zniżka dla subskrybentów względem ceny jednorazowej. Wyświetla się na karcie produktu i stosuje także przy każdym odnowieniu.
• Minimalne zobowiązanie — liczba cykli, po której możliwa jest rezygnacja (0 = rezygnacja dowolna).
• Maksymalna liczba cykli — dla subskrypcji o ograniczonym czasie trwania (0 = bez limitu).
• Dni próbne — okres próbny przed pierwszym rozliczeniem.

Jeden produkt może oferować kilka planów (np. miesięczny -10% i roczny -20%): klient wybiera w bloku „Subskrybuj i oszczędzaj” na karcie produktu.

Ścieżka klienta

Karta produktu

Rozwijany blok prezentuje dostępne plany z cenami po rabacie. Klient wybiera plan (wybór jest zapisywany w bazie, niezawodny nawet przy zmianie urządzenia), a potem normalnie dodaje do koszyka.

Checkout i płatność

Na etapie płatności opcja „Zapłać kartą i aktywuj subskrypcję” pojawia się, jeśli koszyk zawiera wyłącznie produkty subskrypcyjne i klient jest zalogowany. Bezpieczny formularz karty Stripe wyświetla się bezpośrednio na stronie:

1. Klient wpisuje kartę; 3D Secure uruchamia się automatycznie, jeśli wymaga tego jego bank.
2. Płatność pokrywa dokładną sumę koszyka, z kosztami wysyłki włącznie.
3. Karta jest zapisywana w Stripe na kolejne cykle (card on file, ze zgodą zgodną z SCA).
4. Moduł ponownie weryfikuje po stronie serwera status i kwotę płatności przed utworzeniem zamówienia — przeglądarce nigdy nie wierzy się na słowo.

Odnowienia

Przy każdym wykonaniu crona, dla każdej subskrypcji z upływającym terminem:

1. Moduł odbudowuje prawdziwy koszyk PrestaShop: produkt, wariant, adres i pierwotny przewoźnik.
2. Rabat planu jest stosowany przez automatyczną, jednorazową regułę koszyka.
3. Dokładna suma jest liczona natywnym silnikiem cen — z podatkami i kosztami wysyłki, jeśli opcja „Wysyłka przy odnowieniach” jest włączona (domyślnie jest).
4. Zapisana karta jest obciążana off-session dokładnie na tę kwotę.
5. Tworzone jest standardowe zamówienie PrestaShop, ze statusem zamówienia Twojego wyboru (konfigurowalny, np. dedykowany status „Odnowienie”).
6. Klient dostaje e-mail potwierdzenia odnowienia; zdarzenie jest logowane.

Każde zamówienie odnowienia jest widoczne w Zamówieniach jak każda sprzedaż, z powiązaną transakcją Stripe — Twoje eksporty księgowe i zarządzanie stanami działają bez zmian.

Dunning: obsługa nieudanych płatności

Gdy obciążenie przy odnowieniu się nie powiedzie (karta wygasła, limit, odmowa banku):

1. Subskrypcja przechodzi w status „płatność nieudana”, a klient natychmiast otrzymuje e-mail z prośbą o aktualizację karty.
2. Cron automatycznie ponawia płatność — domyślnie 3 próby co 3 dni, obie wartości są konfigurowalne.
3. Po skonfigurowanej liczbie kolejnych niepowodzeń subskrypcja jest automatycznie anulowana, a klient o tym informowany.

Każda próba i jej wynik są logowane w logach subskrypcji. W praktyce dunning odzyskuje 50 do 70% płatności, które przepadłyby przy twardym niepowodzeniu.

Panel klienta „Moje subskrypcje”

Dostępny z konta klienta, panel wyświetla subskrypcje z ich statusem, następną datą rozliczenia i dostawy. Zależnie od Twoich ustawień klient może:

• Wstrzymać / wznowić — daty są przeliczane przy wznowieniu.
• Pominąć następny cykl — rozliczenie i dostawa przesuwają się razem o jeden okres.
• Zrezygnować — dowolnie albo dopiero po minimalnym zobowiązaniu planu. Przy rezygnacji zapisana karta jest automatycznie odłączana w Stripe i wysyłany jest e-mail potwierdzający.

Każda akcja wymaga potwierdzenia i realizuje wzorzec POST-redirect-GET: brak możliwości podwójnego wysłania, natywne komunikaty potwierdzenia PrestaShop.

Back-office

• Dashboard — MRR, aktywne subskrypcje, wskaźnik churn, nieudane płatności, URL crona i webhooka gotowe do skopiowania.
• Subskrypcje — lista filtrowana po statusie, częstotliwości i kliencie; widok szczegółowy z historią wygenerowanych zamówień i logami oraz bezpośrednimi linkami do zamówienia i karty klienta.
• Plany — przegląd wszystkich istniejących planów (tworzenie odbywa się z karty produktu).
• Logi — wszystkie zdarzenia z sygnaturą czasu: utworzenia, odnowienia, niepowodzenia, ponaglenia, wstrzymania, rezygnacje, odebrane webhooki.

FAQ techniczne i rozwiązywanie problemów

Opcja płatności nie pojawia się przy checkoutcie

• Sprawdź, czy koszyk zawiera wyłącznie produkty z wybranym planem i czy klient jest zalogowany.
• Sprawdź, czy klucze Stripe aktywnego trybu są wpisane.
• Jeśli właśnie migrowałeś z wersji 1.x: przeinstaluj moduł lub uruchom ponownie aktualizację — ograniczenia walut/krajów/przewoźników są dodawane przez skrypty migracji 2.x i są niezbędne do wyświetlania opcji.

Odnowienia się nie uruchamiają

• Sprawdź, czy zadanie cron jest zaplanowane i czy jego URL zawiera właściwy token (przetestuj URL w przeglądarce: powinien odpowiedzieć podsumowaniem JSON).
• Zajrzyj do zakładki Logi: każde wykonanie crona zostawia tam ślad.

Płatność 3DS pozostaje „oczekująca”

Jeśli klient zamknie stronę podczas uwierzytelniania 3D Secure, nie następuje żadne obciążenie i nie powstaje zamówienie. Może po prostu złożyć zamówienie ponownie; poprzednia płatność sama wygaśnie po stronie Stripe.

Jak przetestować pełną ścieżkę?

1. Przełącz moduł w tryb testowy i wpisz klucze pk_test/sk_test.
2. Utwórz plan na produkcie, złóż zamówienie kartą 4242 4242 4242 4242 (lub 4000 0027 6000 3184, aby wymusić wyzwanie 3DS).
3. W bazie przestaw datę next_billing_date subskrypcji na wczoraj, potem wywołaj URL crona: powinno pojawić się zamówienie odnowienia.
4. Do testu dunningu użyj karty 4000 0000 0000 0341 (niepowodzenie przy obciążeniu off-session).