DataFirefly Subscriptions — Guide complet (PrestaShop 8 & 9)

Présentation

DataFirefly Subscriptions transforme votre boutique PrestaShop 8 ou 9 en machine à revenus récurrents. Le module repose sur une architecture « card on file » : le client paie une seule fois au checkout via une option de paiement native, sa carte est enregistrée de façon sécurisée chez Stripe, puis un cron quotidien débite automatiquement la carte à chaque échéance et crée une vraie commande PrestaShop au montant exact, frais de port inclus.

Points clés de l’architecture :

• Un seul moteur de facturation — aucun objet Subscription côté Stripe, tout est piloté par votre boutique. Les doubles débits sont structurellement impossibles.
• Montants exacts — chaque renouvellement reconstruit un panier réel et calcule le total via le moteur de prix PrestaShop (remises, taxes, port).
• 3DS/SCA géré — l’authentification forte est gérée au paiement initial ; les renouvellements utilisent le mécanisme off-session conforme SCA.
• Aucune donnée bancaire côté PrestaShop — la conformité PCI-DSS est portée par Stripe.

Installation

1. Téléchargez le ZIP du module depuis votre compte client DataFirefly.
2. Dans votre back-office PrestaShop : Modules → Gestionnaire de modules → Installer un module, puis sélectionnez le ZIP.
3. Le module crée automatiquement ses tables, ses onglets d’administration (Abonnements, Plans, Logs, Dashboard) et enregistre ses hooks.
4. Cliquez sur Configurer pour ouvrir la page de configuration.

Configuration Stripe

Clés API

Dans la configuration du module, renseignez vos clés Stripe. Le module gère deux jeux de clés distincts :

• Mode test : clé publique pk_test_... et clé secrète sk_test_... — pour valider le parcours complet sans débit réel (carte de test 4242 4242 4242 4242).
• Mode live : clé publique pk_live_... et clé secrète sk_live_... — pour la production.

Vous trouverez ces clés dans votre dashboard Stripe : Développeurs → Clés API. Basculez entre test et live avec l’interrupteur « Mode » du module.

Webhook

Le webhook sert uniquement aux événements exceptionnels (la facturation est pilotée par le cron, pas par Stripe). Dans votre dashboard Stripe : Développeurs → Webhooks → Ajouter un endpoint, avec l’URL affichée dans la configuration du module (de la forme https://votreboutique.fr/module/dfsubscription/webhook), et abonnez-vous à ces trois événements :

• payment_method.detached — carte supprimée côté Stripe : l’abonnement passe en « paiement échoué » pour vous prévenir avant l’échéance.
• charge.dispute.created — litige (chargeback) : journalisé sur l’abonnement concerné.
• charge.refunded — remboursement : journalisé sur l’abonnement concerné.

Copiez ensuite le secret de signature (whsec_...) fourni par Stripe dans le champ correspondant de la configuration.

Configuration du cron

Le cron est le moteur des renouvellements : il détecte chaque jour les abonnements arrivés à échéance, débite les cartes enregistrées et crée les commandes. L’URL sécurisée par token est affichée dans la configuration et le dashboard du module, de la forme :

https://votreboutique.fr/module/dfsubscription/cron?token=VOTRE_TOKEN

Créez une tâche cron quotidienne chez votre hébergeur (cPanel, Plesk, crontab) qui appelle cette URL. Exemple crontab pour une exécution chaque jour à 6h00 :

0 6 * * * curl -s "https://votreboutique.fr/module/dfsubscription/cron?token=VOTRE_TOKEN" > /dev/null 2>&1

Créer des plans d’abonnement

Les plans se gèrent directement depuis la fiche produit du back-office : Catalogue → Produits → votre produit → onglet Modules / DataFirefly Subscriptions. Pour chaque plan, définissez :

• Fréquence de facturation — hebdomadaire, bimensuelle, mensuelle, trimestrielle, semestrielle ou annuelle.
• Fréquence de livraison — identique à la facturation, hebdomadaire, bimensuelle ou mensuelle. Exemple : facturation mensuelle + livraison hebdomadaire = box hebdo à paiement mensuel.
• Remise (%) — la réduction accordée aux abonnés par rapport au prix one-shot. Elle s’affiche sur la fiche produit et s’applique aussi à chaque renouvellement.
• Engagement minimum — nombre de cycles avant que la résiliation soit possible (0 = résiliation libre).
• Cycles maximum — pour des abonnements à durée limitée (0 = illimité).
• Jours d’essai — période d’essai avant la première facturation.

Un produit peut proposer plusieurs plans (ex. mensuel -10 % et annuel -20 %) : le client choisit dans le bloc « Abonnez-vous et économisez » de la fiche produit.

Parcours client

Fiche produit

Un bloc dépliable présente les plans disponibles avec leurs prix remisés. Le client sélectionne son plan (la sélection est enregistrée en base, fiable même s’il change d’appareil), puis ajoute au panier normalement.

Checkout et paiement

À l’étape paiement, l’option « Payer par carte et activer mon abonnement » apparaît si le panier contient uniquement des produits en abonnement et que le client est connecté. Le formulaire carte sécurisé Stripe s’affiche directement dans la page :

1. Le client saisit sa carte ; le 3D Secure se déclenche automatiquement si sa banque l’exige.
2. Le paiement couvre le total exact du panier, frais de port inclus.
3. La carte est enregistrée chez Stripe pour les cycles suivants (card on file, avec consentement conforme SCA).
4. Le module re-vérifie côté serveur le statut et le montant du paiement avant de créer la commande — le navigateur n’est jamais cru sur parole.

Renouvellements

À chaque exécution du cron, pour chaque abonnement arrivé à échéance :

1. Le module reconstruit un vrai panier PrestaShop : produit, déclinaison, adresse et transporteur d’origine.
2. La remise du plan est appliquée via une règle panier automatique à usage unique.
3. Le total exact est calculé par le moteur de prix natif — taxes et frais de port inclus si l’option « Port sur les renouvellements » est activée (elle l’est par défaut).
4. La carte enregistrée est débitée hors session pour précisément ce montant.
5. Une commande PrestaShop standard est créée, avec l’état de commande de votre choix (configurable, ex. un état dédié « Renouvellement »).
6. Le client reçoit l’email de confirmation de renouvellement ; l’événement est journalisé.

Chaque commande de renouvellement est visible dans Commandes comme n’importe quelle vente, avec sa transaction Stripe associée — vos exports comptables et votre gestion de stock fonctionnent sans modification.

Dunning : gestion des échecs de paiement

Quand un débit de renouvellement échoue (carte expirée, plafond, refus bancaire) :

1. L’abonnement passe en statut « paiement échoué » et le client reçoit immédiatement un email de relance l’invitant à mettre à jour sa carte.
2. Le cron retente automatiquement le paiement — par défaut 3 tentatives à 3 jours d’intervalle, les deux valeurs étant configurables.
3. Après le nombre d’échecs consécutifs configuré, l’abonnement est annulé automatiquement et le client en est informé.

Chaque tentative et son résultat sont journalisés dans les logs de l’abonnement. En pratique, le dunning récupère 50 à 70 % des paiements qui auraient été perdus en échec sec.

Espace client « Mes abonnements »

Accessible depuis le compte client, cet espace liste les abonnements avec leur statut, la prochaine date de facturation et de livraison. Selon vos réglages, le client peut :

• Mettre en pause / reprendre — les dates sont recalculées à la reprise.
• Sauter le prochain cycle — la facturation et la livraison sont décalées ensemble d’une période.
• Résilier — librement, ou seulement après l’engagement minimum du plan. À la résiliation, la carte enregistrée est automatiquement détachée chez Stripe et un email de confirmation est envoyé.

Chaque action demande une confirmation et suit le pattern POST-redirect-GET : pas de double soumission possible, messages de confirmation natifs PrestaShop.

Back-office

• Dashboard — MRR, abonnements actifs, taux de churn, paiements en échec, URL de cron et de webhook prêtes à copier.
• Abonnements — liste filtrable par statut, fréquence et client ; vue détaillée avec l’historique des commandes générées et les logs, et liens directs vers la commande et la fiche client.
• Plans — vue d’ensemble de tous les plans existants (la création se fait depuis la fiche produit).
• Logs — tous les événements horodatés : créations, renouvellements, échecs, relances, pauses, résiliations, webhooks reçus.

FAQ technique et dépannage

L’option de paiement n’apparaît pas au checkout

• Vérifiez que le panier ne contient que des produits avec un plan sélectionné et que le client est connecté.
• Vérifiez que les clés Stripe du mode actif sont renseignées.
• Si vous venez de migrer depuis une version 1.x : réinstallez le module ou relancez la mise à jour — les restrictions devises/pays/transporteurs sont ajoutées par les scripts de migration 2.x et sont indispensables à l’affichage de l’option.

Les renouvellements ne se déclenchent pas

• Vérifiez que la tâche cron est bien planifiée et que son URL contient le bon token (testez l’URL dans un navigateur : elle doit répondre avec un résumé JSON).
• Consultez l’onglet Logs : chaque exécution du cron y laisse une trace.

Un paiement 3DS reste « en attente »

Si le client ferme la page pendant l’authentification 3D Secure, aucun débit n’a lieu et aucune commande n’est créée. Il peut simplement repasser commande ; le paiement précédent expirera de lui-même côté Stripe.

Comment tester le parcours complet ?

1. Passez le module en mode test et renseignez les clés pk_test/sk_test.
2. Créez un plan sur un produit, passez une commande avec la carte 4242 4242 4242 4242 (ou 4000 0027 6000 3184 pour forcer un défi 3DS).
3. Dans la base, avancez la date next_billing_date de l’abonnement à hier, puis appelez l’URL de cron : une commande de renouvellement doit apparaître.
4. Pour tester le dunning, utilisez la carte 4000 0000 0000 0341 (échec au débit off-session).