DataFirefly Subscriptions: volledige gids (PrestaShop 8 en 9)

Overzicht

DataFirefly Subscriptions maakt van uw PrestaShop 8- of 9-winkel een machine voor terugkerende omzet. De module berust op een « card on file »-architectuur: de klant betaalt één keer bij het afrekenen via een native betaaloptie, zijn kaart wordt veilig bij Stripe opgeslagen, en een dagelijkse cron incasseert bij elke vervaldag automatisch van die kaart en maakt een echte PrestaShop-bestelling aan voor het exacte bedrag, verzendkosten inbegrepen.

Kernpunten van de architectuur:

• Eén enkele facturatiemotor: geen Subscription-object aan de kant van Stripe, alles wordt door uw winkel aangestuurd. Dubbele afschrijvingen zijn structureel onmogelijk.
• Exacte bedragen: elke verlenging bouwt een echte winkelwagen op en berekent het totaal via de prijsmotor van PrestaShop (kortingen, btw, verzending).
• 3DS/SCA afgehandeld: de sterke authenticatie verloopt bij de eerste betaling; de verlengingen gebruiken het SCA-conforme off-sessionmechanisme.
• Geen bankgegevens binnen PrestaShop: de PCI-DSS-conformiteit ligt bij Stripe.

Installatie

1. Download de ZIP van de module vanuit uw DataFirefly-klantaccount.
2. Ga in uw PrestaShop-backoffice naar Modules → Modulebeheer → Een module installeren en selecteer de ZIP.
3. De module maakt automatisch zijn tabellen en beheertabbladen (Abonnementen, Plannen, Logboek, Dashboard) aan en registreert zijn hooks.
4. Klik op Configureren om de configuratiepagina te openen.

Stripe-configuratie

API-sleutels

Vul in de configuratie van de module uw Stripe-sleutels in. De module beheert twee gescheiden sets sleutels:

• Testmodus: publieke sleutel pk_test_... en geheime sleutel sk_test_..., om het volledige traject te valideren zonder echte afschrijving (testkaart 4242 4242 4242 4242).
• Livemodus: publieke sleutel pk_live_... en geheime sleutel sk_live_..., voor productie.

U vindt deze sleutels in uw Stripe-dashboard onder Ontwikkelaars → API-sleutels. Wissel tussen test en live met de schakelaar « Modus » van de module.

Webhook

De webhook dient uitsluitend voor uitzonderlijke gebeurtenissen (de facturatie wordt door de cron aangestuurd, niet door Stripe). Ga in uw Stripe-dashboard naar Ontwikkelaars → Webhooks → Een endpoint toevoegen, met de URL die in de configuratie van de module wordt getoond (van de vorm https://uwwinkel.nl/module/dfsubscription/webhook), en abonneer u op deze drie gebeurtenissen:

• payment_method.detached: kaart verwijderd bij Stripe, waarna het abonnement op « betaling mislukt » gaat om u vóór de vervaldag te waarschuwen.
• charge.dispute.created: geschil (chargeback), gelogd op het betrokken abonnement.
• charge.refunded: terugbetaling, gelogd op het betrokken abonnement.

Kopieer daarna het ondertekeningsgeheim (whsec_...) van Stripe naar het bijbehorende veld in de configuratie.

De cron instellen

De cron is de motor achter de verlengingen: hij detecteert elke dag de vervallen abonnementen, incasseert van de opgeslagen kaarten en maakt de bestellingen aan. De met een token beveiligde URL staat in de configuratie en op het dashboard van de module, van de vorm:

https://uwwinkel.nl/module/dfsubscription/cron?token=UW_TOKEN

Maak bij uw host een dagelijkse crontaak aan (cPanel, Plesk, crontab) die deze URL aanroept. Voorbeeld van een crontab voor een uitvoering elke dag om 6.00 uur:

0 6 * * * curl -s "https://uwwinkel.nl/module/dfsubscription/cron?token=UW_TOKEN" > /dev/null 2>&1

Abonnementsplannen aanmaken

Plannen beheert u rechtstreeks vanaf de productfiche in de backoffice: Catalogus → Producten → uw product → tabblad Modules / DataFirefly Subscriptions. Bepaal per plan:

• Facturatiefrequentie: wekelijks, tweewekelijks, maandelijks, per kwartaal, per half jaar of jaarlijks.
• Leveringsfrequentie: gelijk aan de facturatie, wekelijks, tweewekelijks of maandelijks. Voorbeeld: maandelijkse facturatie + wekelijkse levering = weekbox met maandelijkse betaling.
• Korting (%): de korting voor abonnees ten opzichte van de eenmalige prijs. Die wordt op de productfiche getoond en geldt ook bij elke verlenging.
• Minimale looptijd: aantal cycli voordat opzeggen mogelijk is (0 = vrij opzegbaar).
• Maximaal aantal cycli: voor abonnementen met beperkte duur (0 = onbeperkt).
• Proefdagen: proefperiode vóór de eerste facturatie.

Eén product kan meerdere plannen aanbieden (bijvoorbeeld maandelijks -10 % en jaarlijks -20 %): de klant kiest in het blok « Abonneer u en bespaar » op de productfiche.

Klanttraject

Productfiche

Een uitklapbaar blok toont de beschikbare plannen met hun kortingsprijzen. De klant kiest zijn plan (de keuze wordt in de database opgeslagen en blijft betrouwbaar, ook als hij van apparaat wisselt) en legt het product daarna gewoon in de winkelwagen.

Afrekenen en betaling

Bij de betaalstap verschijnt de optie « Met kaart betalen en mijn abonnement activeren » als de winkelwagen uitsluitend abonnementsproducten bevat en de klant is ingelogd. Het beveiligde kaartformulier van Stripe verschijnt rechtstreeks in de pagina:

1. De klant voert zijn kaart in; 3D Secure wordt automatisch geactiveerd als zijn bank dat vereist.
2. De betaling dekt het exacte totaal van de winkelwagen, verzendkosten inbegrepen.
3. De kaart wordt bij Stripe opgeslagen voor de volgende cycli (card on file, met SCA-conforme toestemming).
4. De module controleert aan serverzijde opnieuw de status en het bedrag van de betaling voordat de bestelling wordt aangemaakt: de browser wordt nooit op zijn woord geloofd.

Verlengingen

Bij elke uitvoering van de cron gebeurt voor elk vervallen abonnement het volgende:

1. De module bouwt een echte PrestaShop-winkelwagen op: product, variant, adres en oorspronkelijke vervoerder.
2. De korting van het plan wordt toegepast via een automatische winkelwagenregel voor eenmalig gebruik.
3. Het exacte totaal wordt berekend door de native prijsmotor, inclusief btw en verzendkosten als de optie « Verzendkosten bij verlengingen » aanstaat (standaard het geval).
4. De opgeslagen kaart wordt off-session belast voor precies dat bedrag.
5. Er wordt een standaard PrestaShop-bestelling aangemaakt, met de besteltoestand van uw keuze (instelbaar, bijvoorbeeld een eigen toestand « Verlenging »).
6. De klant ontvangt de bevestigingsmail van de verlenging; de gebeurtenis wordt gelogd.

Elke verlengingsbestelling is zichtbaar in Bestellingen als elke andere verkoop, met de bijbehorende Stripe-transactie: uw boekhoudexports en voorraadbeheer werken zonder aanpassing.

Dunning: omgaan met mislukte betalingen

Wanneer een verlengingsincasso mislukt (verlopen kaart, limiet, weigering door de bank):

1. Het abonnement krijgt de status « betaling mislukt » en de klant ontvangt meteen een herinneringsmail met het verzoek zijn kaart bij te werken.
2. De cron probeert de betaling automatisch opnieuw, standaard 3 pogingen met 3 dagen ertussen, beide waarden instelbaar.
3. Na het ingestelde aantal opeenvolgende mislukkingen wordt het abonnement automatisch geannuleerd en de klant daarover geïnformeerd.

Elke poging en het resultaat ervan worden vastgelegd in het logboek van het abonnement. In de praktijk redt dunning 50 tot 70 % van de betalingen die anders definitief verloren waren gegaan.

Klantenzone « Mijn abonnementen »

Deze zone is bereikbaar vanuit het klantaccount en toont de abonnementen met hun status en de volgende factuur- en leverdatum. Afhankelijk van uw instellingen kan de klant:

• Pauzeren of hervatten: de datums worden bij het hervatten opnieuw berekend.
• De volgende cyclus overslaan: facturatie en levering schuiven samen één periode op.
• Opzeggen: vrij, of pas na de minimale looptijd van het plan. Bij opzegging wordt de opgeslagen kaart automatisch losgekoppeld bij Stripe en volgt er een bevestigingsmail.

Elke actie vraagt om bevestiging en volgt het POST-redirect-GET-patroon: dubbel verzenden is onmogelijk en de bevestigingsmeldingen zijn die van PrestaShop zelf.

Backoffice

• Dashboard: MRR, actieve abonnementen, verlooppercentage, mislukte betalingen, en de cron- en webhook-URL klaar om te kopiëren.
• Abonnementen: lijst te filteren op status, frequentie en klant; detailweergave met de historiek van de gegenereerde bestellingen en het logboek, plus rechtstreekse links naar de bestelling en de klantfiche.
• Plannen: overzicht van alle bestaande plannen (het aanmaken gebeurt vanaf de productfiche).
• Logboek: alle gebeurtenissen met tijdstempel: aanmaken, verlengingen, mislukkingen, herinneringen, pauzes, opzeggingen en ontvangen webhooks.

Beheerdersacties op een abonnement (v2.2)

Vanuit de detailweergave van een abonnement kan een medewerker met wijzigingsrechten rechtstreeks ingrijpen. Elke actie vraagt om bevestiging, wordt met de naam van de beheerder gelogd, en de klant krijgt bericht per e-mail waar dat relevant is:

• Pauzeren / hervatten: bij het hervatten worden de datums vanaf vandaag herberekend en gaat de teller van mislukkingen terug naar nul.
• De volgende cyclus overslaan: facturatie en levering schuiven samen één periode op.
• Nu factureren: belast onmiddellijk de opgeslagen kaart via dezelfde motor als de cron (opnieuw opgebouwde winkelwagen, exact totaal) en maakt de bestelling aan. Ideaal om een abonnement in « betaling mislukt » weer op gang te brengen nadat de klant zijn kaart heeft bijgewerkt; mislukt het opnieuw, dan neemt de normale dunning het over.
• De volgende datums aanpassen: rechtstreekse bewerking van de volgende facturatie en de volgende levering.
• Van plan wisselen: overstappen naar een ander actief plan van hetzelfde product, geldig vanaf de volgende cycli (de datum van de volgende facturatie verandert niet).
• Opzeggen: optionele reden wordt gelogd, het loskoppelen van de kaart staat standaard aangevinkt. De beheerder is, anders dan de klant, niet gebonden aan de minimale looptijd.

In de lijst met abonnementen zijn twee groepsacties beschikbaar: pauzeren en opzeggen in bulk. Abonnementen in een onverenigbare toestand worden overgeslagen en meegeteld in de resultaatmelding.

Technische FAQ en probleemoplossing

De betaaloptie verschijnt niet bij het afrekenen

• Controleer of de winkelwagen uitsluitend producten met een gekozen plan bevat en of de klant is ingelogd.
• Controleer of de Stripe-sleutels van de actieve modus zijn ingevuld.
• Bent u net gemigreerd vanaf een 1.x-versie: installeer de module opnieuw of start de update opnieuw. De beperkingen voor valuta, landen en vervoerders worden door de 2.x-migratiescripts toegevoegd en zijn onmisbaar om de optie te tonen.

De verlengingen komen niet op gang

• Controleer of de crontaak is ingepland en of de URL het juiste token bevat (test de URL in een browser: die hoort een JSON-samenvatting terug te geven).
• Raadpleeg het tabblad Logboek: elke uitvoering van de cron laat daar een spoor na.

Een 3DS-betaling blijft « in afwachting »

Sluit de klant de pagina tijdens de 3D Secure-authenticatie, dan vindt er geen afschrijving plaats en wordt er geen bestelling aangemaakt. Hij kan de bestelling gewoon opnieuw plaatsen; de vorige betaling verloopt vanzelf aan de kant van Stripe.

Hoe test ik het volledige traject?

1. Zet de module in testmodus en vul de sleutels pk_test/sk_test in.
2. Maak een plan aan op een product en plaats een bestelling met de kaart 4242 4242 4242 4242 (of 4000 0027 6000 3184 om een 3DS-uitdaging af te dwingen).
3. Zet in de database de datum next_billing_date van het abonnement op gisteren en roep daarna de cron-URL aan: er hoort een verlengingsbestelling te verschijnen.
4. Gebruik voor het testen van de dunning de kaart 4000 0000 0000 0341 (mislukking bij off-session incasso).