DataFirefly Subscriptions — Komplette Anleitung (PrestaShop 8 & 9)

Überblick

DataFirefly Subscriptions verwandelt Ihren PrestaShop-8- oder -9-Shop in eine Maschine für wiederkehrende Umsätze. Das Modul basiert auf einer Card-on-File-Architektur: Der Kunde zahlt einmal im Checkout über eine native Zahlungsoption, seine Karte wird sicher bei Stripe hinterlegt, und ein täglicher Cron belastet die Karte automatisch bei jeder Fälligkeit und erzeugt eine echte PrestaShop-Bestellung über den exakten Betrag, Versandkosten inklusive.

Zentrale Architekturpunkte:

• Eine einzige Abrechnungs-Engine — kein Subscription-Objekt bei Stripe, alles wird von Ihrem Shop gesteuert. Doppelabbuchungen sind strukturell unmöglich.
• Exakte Beträge — jede Verlängerung baut einen echten Warenkorb neu auf und berechnet den Betrag über die PrestaShop-Preisengine (Rabatte, Steuern, Versand).
• 3DS/SCA abgewickelt — die starke Kundenauthentifizierung erfolgt bei der Erstzahlung; Verlängerungen nutzen den SCA-konformen Off-Session-Mechanismus.
• Keine Bankdaten auf PrestaShop — die PCI-DSS-Konformität trägt Stripe.

Installation

1. Laden Sie das Modul-ZIP aus Ihrem DataFirefly-Kundenkonto herunter.
2. In Ihrem PrestaShop-Backoffice: Module → Modul-Manager → Modul hochladen, dann das ZIP auswählen.
3. Das Modul erstellt automatisch seine Tabellen, seine Admin-Tabs (Abonnements, Pläne, Logs, Dashboard) und registriert seine Hooks.
4. Klicken Sie auf Konfigurieren, um die Konfigurationsseite zu öffnen.

Stripe-Konfiguration

API-Schlüssel

Tragen Sie in der Modulkonfiguration Ihre Stripe-Schlüssel ein. Das Modul verwaltet zwei getrennte Schlüsselsätze:

• Testmodus: öffentlicher Schlüssel pk_test_... und geheimer Schlüssel sk_test_... — um den kompletten Ablauf ohne echte Abbuchungen zu prüfen (Testkarte 4242 4242 4242 4242).
• Livemodus: öffentlicher Schlüssel pk_live_... und geheimer Schlüssel sk_live_... — für die Produktion.

Sie finden diese Schlüssel in Ihrem Stripe-Dashboard: Entwickler → API-Schlüssel. Wechseln Sie mit dem Modus-Schalter des Moduls zwischen Test und Live.

Webhook

Der Webhook dient nur Ausnahmeereignissen (die Abrechnung steuert der Cron, nicht Stripe). In Ihrem Stripe-Dashboard: Entwickler → Webhooks → Endpoint hinzufügen, mit der in der Modulkonfiguration angezeigten URL (in der Form https://ihrshop.de/module/dfsubscription/webhook), und abonnieren Sie diese drei Ereignisse:

• payment_method.detached — Karte bei Stripe gelöscht: Das Abonnement wechselt auf „Zahlung fehlgeschlagen“, damit Sie vor der Fälligkeit gewarnt sind.
• charge.dispute.created — Streitfall (Chargeback): am betroffenen Abonnement protokolliert.
• charge.refunded — Erstattung: am betroffenen Abonnement protokolliert.

Kopieren Sie anschließend das von Stripe bereitgestellte Signatur-Secret (whsec_...) in das entsprechende Konfigurationsfeld.

Cron-Konfiguration

Der Cron ist die Verlängerungs-Engine: Er erkennt täglich die fälligen Abonnements, belastet die hinterlegten Karten und erzeugt die Bestellungen. Die token-gesicherte URL wird in der Konfiguration und im Dashboard des Moduls angezeigt, in der Form:

https://ihrshop.de/module/dfsubscription/cron?token=IHR_TOKEN

Legen Sie bei Ihrem Hoster (cPanel, Plesk, crontab) einen täglichen Cronjob an, der diese URL aufruft. Crontab-Beispiel für eine Ausführung jeden Tag um 6:00 Uhr:

0 6 * * * curl -s "https://ihrshop.de/module/dfsubscription/cron?token=IHR_TOKEN" > /dev/null 2>&1

Abonnementpläne erstellen

Pläne werden direkt auf der Backoffice-Produktseite verwaltet: Katalog → Produkte → Ihr Produkt → Tab Module / DataFirefly Subscriptions. Definieren Sie für jeden Plan:

• Abrechnungsfrequenz — wöchentlich, 14-tägig, monatlich, vierteljährlich, halbjährlich oder jährlich.
• Lieferfrequenz — wie die Abrechnung, wöchentlich, 14-tägig oder monatlich. Beispiel: monatliche Abrechnung + wöchentliche Lieferung = Wochenbox mit Monatszahlung.
• Rabatt (%) — der Nachlass für Abonnenten gegenüber dem Einzelkaufpreis. Er wird auf der Produktseite angezeigt und auch bei jeder Verlängerung angewendet.
• Mindestlaufzeit — Anzahl der Zyklen, bevor eine Kündigung möglich wird (0 = freie Kündigung).
• Maximale Zyklen — für Abonnements mit begrenzter Laufzeit (0 = unbegrenzt).
• Testtage — Testphase vor der ersten Abrechnung.

Ein Produkt kann mehrere Pläne anbieten (z. B. monatlich -10 % und jährlich -20 %): Der Kunde wählt im Block „Abonnieren und sparen“ auf der Produktseite.

Customer Journey

Produktseite

Ein aufklappbarer Block präsentiert die verfügbaren Pläne mit ihren Rabattpreisen. Der Kunde wählt seinen Plan (die Auswahl wird in der Datenbank gespeichert, zuverlässig auch bei Gerätewechsel) und legt normal in den Warenkorb.

Checkout und Zahlung

Im Zahlungsschritt erscheint die Option „Mit Karte zahlen und Abonnement aktivieren“, wenn der Warenkorb nur Abonnementprodukte enthält und der Kunde angemeldet ist. Das sichere Stripe-Kartenformular wird direkt in der Seite angezeigt:

1. Der Kunde gibt seine Karte ein; 3D Secure wird automatisch ausgelöst, wenn seine Bank es verlangt.
2. Die Zahlung deckt den exakten Warenkorbbetrag, Versand inklusive.
3. Die Karte wird für die folgenden Zyklen bei Stripe hinterlegt (Card on File, mit SCA-konformer Zustimmung).
4. Das Modul prüft Status und Betrag der Zahlung serverseitig nach, bevor die Bestellung erstellt wird — dem Browser wird nie blind vertraut.

Verlängerungen

Bei jedem Cron-Lauf, für jedes fällige Abonnement:

1. Das Modul baut einen echten PrestaShop-Warenkorb neu auf: Produkt, Variante, ursprüngliche Adresse und Versanddienst.
2. Der Plan-Rabatt wird über eine automatische Einmal-Warenkorbregel angewendet.
3. Der exakte Betrag wird von der nativen Preisengine berechnet — Steuern und Versand inklusive, wenn die Option „Versand bei Verlängerungen“ aktiviert ist (Standard).
4. Die hinterlegte Karte wird off-session über genau diesen Betrag belastet.
5. Eine Standard-PrestaShop-Bestellung wird erstellt, mit dem Bestellstatus Ihrer Wahl (konfigurierbar, z. B. ein dedizierter Status „Verlängerung“).
6. Der Kunde erhält die Verlängerungsbestätigung per E-Mail; das Ereignis wird protokolliert.

Jede Verlängerungsbestellung ist unter Bestellungen sichtbar wie jeder Verkauf, mit ihrer zugehörigen Stripe-Transaktion — Ihre Buchhaltungsexporte und Ihre Lagerverwaltung funktionieren unverändert.

Dunning: Umgang mit Zahlungsfehlschlägen

Wenn eine Verlängerungsabbuchung fehlschlägt (abgelaufene Karte, Limit, Bankablehnung):

1. Das Abonnement wechselt in den Status „Zahlung fehlgeschlagen“ und der Kunde erhält sofort eine Erinnerungs-E-Mail mit der Bitte, seine Karte zu aktualisieren.
2. Der Cron wiederholt die Zahlung automatisch — standardmäßig 3 Versuche alle 3 Tage, beide Werte konfigurierbar.
3. Nach der konfigurierten Anzahl aufeinanderfolgender Fehlschläge wird das Abonnement automatisch gekündigt und der Kunde informiert.

Jeder Versuch und sein Ergebnis werden in den Logs des Abonnements protokolliert. In der Praxis rettet Dunning 50 bis 70 % der Zahlungen, die sonst verloren gegangen wären.

Der Kundenbereich „Meine Abonnements“

Erreichbar über das Kundenkonto, listet dieser Bereich die Abonnements mit Status, nächstem Abrechnungs- und Lieferdatum. Je nach Ihren Einstellungen kann der Kunde:

• Pausieren / fortsetzen — die Termine werden bei der Fortsetzung neu berechnet.
• Den nächsten Zyklus überspringen — Abrechnung und Lieferung werden gemeinsam um eine Periode verschoben.
• Kündigen — frei oder erst nach der Mindestlaufzeit des Plans. Bei der Kündigung wird die hinterlegte Karte automatisch bei Stripe entfernt und eine Bestätigungs-E-Mail gesendet.

Jede Aktion erfordert eine Bestätigung und folgt dem POST-Redirect-GET-Muster: keine Doppelübermittlung möglich, native PrestaShop-Bestätigungsmeldungen.

Backoffice

• Dashboard — MRR, aktive Abonnements, Churn-Rate, fehlgeschlagene Zahlungen, Cron- und Webhook-URLs zum Kopieren bereit.
• Abonnements — Liste filterbar nach Status, Frequenz und Kunde; Detailansicht mit der Historie der erzeugten Bestellungen und den Logs sowie Direktlinks zur Bestellung und zur Kundenakte.
• Pläne — Übersicht aller bestehenden Pläne (die Erstellung erfolgt auf der Produktseite).
• Logs — alle zeitgestempelten Ereignisse: Erstellungen, Verlängerungen, Fehlschläge, Wiederholungen, Pausen, Kündigungen, empfangene Webhooks.

Technische FAQ und Fehlerbehebung

Die Zahlungsoption erscheint nicht im Checkout

• Prüfen Sie, dass der Warenkorb nur Produkte mit ausgewähltem Plan enthält und der Kunde angemeldet ist.
• Prüfen Sie, dass die Stripe-Schlüssel des aktiven Modus eingetragen sind.
• Wenn Sie gerade von einer 1.x-Version migriert haben: Installieren Sie das Modul neu oder führen Sie das Upgrade erneut aus — die Währungs-/Länder-/Versandbeschränkungen werden von den 2.x-Migrationsskripten hinzugefügt und sind für die Anzeige der Option unerlässlich.

Die Verlängerungen werden nicht ausgelöst

• Prüfen Sie, dass der Cronjob geplant ist und seine URL das richtige Token enthält (testen Sie die URL im Browser: Sie muss mit einer JSON-Zusammenfassung antworten).
• Sehen Sie im Tab Logs nach: Jeder Cron-Lauf hinterlässt dort eine Spur.

Eine 3DS-Zahlung bleibt „ausstehend“

Schließt der Kunde die Seite während der 3D-Secure-Authentifizierung, findet keine Abbuchung statt und keine Bestellung wird erstellt. Er kann einfach erneut bestellen; die vorherige Zahlung läuft bei Stripe von selbst ab.

Wie teste ich den kompletten Ablauf?

1. Schalten Sie das Modul in den Testmodus und tragen Sie die pk_test/sk_test-Schlüssel ein.
2. Erstellen Sie einen Plan auf einem Produkt und bestellen Sie mit der Karte 4242 4242 4242 4242 (oder 4000 0027 6000 3184, um eine 3DS-Abfrage zu erzwingen).
3. Setzen Sie in der Datenbank das next_billing_date des Abonnements auf gestern und rufen Sie die Cron-URL auf: Eine Verlängerungsbestellung muss erscheinen.
4. Zum Testen des Dunnings verwenden Sie die Karte 4000 0000 0000 0341 (Fehlschlag bei Off-Session-Abbuchung).