# 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ą…

- Strona: <https://www.datafirefly.com/pl/documentation/datafirefly-subscriptions/>
- Język: pl
- Zaktualizowano: 2026-08-12
- Inne języki: [fr](https://www.datafirefly.com/documentation/datafirefly-subscriptions/index.md), [en](https://www.datafirefly.com/en/documentation/datafirefly-subscriptions/index.md), [es](https://www.datafirefly.com/es/documentation/datafirefly-subscriptions/index.md), [de](https://www.datafirefly.com/de/documentation/datafirefly-subscriptions/index.md), [it](https://www.datafirefly.com/it/documentation/datafirefly-subscriptions/index.md), [pt](https://www.datafirefly.com/pt/documentation/datafirefly-subscriptions/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafirefly-subscriptions/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

## 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.

**Wymagania:** PrestaShop 8.0 do 9.x, PHP 8.0 do 8.4, konto Stripe (darmowe) i możliwość utworzenia zadania cron u hostingodawcy. Composer nie jest wymagany.

**Aktualizacja z wersji 1.x:** po prostu zainstaluj nowy ZIP na wierzchu. Skrypty migracji wykonują się automatycznie i rejestrują m.in. ograniczenia walut/krajów/przewoźników niezbędne do wyświetlania opcji płatności przy checkoutcie.

## 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.

**Ważne:** w trybie live niepodpisane żądania webhook są odrzucane. Koniecznie wpisz sekret podpisu przed przejściem na produkcję.

## 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
```

Jedno wykonanie dziennie wystarcza: moduł przetwarza w jednym przebiegu wszystkie wymagalne subskrypcje, z wydłużonym limitem czasu dla dużych wolumenów. Możesz też użyć usługi zewnętrznej jak cron-job.org, jeśli hosting nie oferuje crona.

## 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.

Koszyki mieszane (subskrypcja + produkt klasyczny) są blokowane po stronie klienta i serwera: klient jest proszony o finalizację osobno. To gwarantuje zawsze spójne kwoty odnowień.

## 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).

Potrzebujesz pomocy? Otwórz zgłoszenie ze swojego konta klienta DataFirefly — odpowiedź w ciągu 24 h roboczych, po francusku lub angielsku.