DataFirefly Subscriptions — Guida completa (PrestaShop 8 e 9)

Panoramica

DataFirefly Subscriptions trasforma il vostro negozio PrestaShop 8 o 9 in una macchina di ricavi ricorrenti. Il modulo si basa su un’architettura « card on file »: il cliente paga una sola volta al checkout tramite un’opzione di pagamento nativa, la sua carta viene memorizzata in modo sicuro su Stripe, poi un cron giornaliero addebita automaticamente la carta a ogni scadenza e crea un vero ordine PrestaShop per l’importo esatto, spese di spedizione incluse.

Punti chiave dell’architettura:

• Un unico motore di fatturazione — nessun oggetto Subscription su Stripe, tutto è guidato dal vostro negozio. I doppi addebiti sono strutturalmente impossibili.
• Importi esatti — ogni rinnovo ricostruisce un carrello reale e calcola il totale con il motore prezzi di PrestaShop (sconti, tasse, spedizione).
• 3DS/SCA gestito — l’autenticazione forte è gestita al pagamento iniziale; i rinnovi usano il meccanismo off-session conforme SCA.
• Nessun dato bancario su PrestaShop — la conformità PCI-DSS è a carico di Stripe.

Installazione

1. Scaricate lo ZIP del modulo dal vostro account cliente DataFirefly.
2. Nel back office di PrestaShop: Moduli → Gestione moduli → Carica un modulo, poi selezionate lo ZIP.
3. Il modulo crea automaticamente le sue tabelle, le sue schede di amministrazione (Abbonamenti, Piani, Log, Dashboard) e registra i suoi hook.
4. Cliccate su Configura per aprire la pagina di configurazione.

Configurazione Stripe

Chiavi API

Nella configurazione del modulo, inserite le vostre chiavi Stripe. Il modulo gestisce due set di chiavi distinti:

• Modalità test: chiave pubblica pk_test_... e chiave segreta sk_test_... — per validare il percorso completo senza addebiti reali (carta di prova 4242 4242 4242 4242).
• Modalità live: chiave pubblica pk_live_... e chiave segreta sk_live_... — per la produzione.

Trovate queste chiavi nel vostro dashboard Stripe: Sviluppatori → Chiavi API. Passate da test a live con l’interruttore «Modalità» del modulo.

Webhook

Il webhook serve solo per gli eventi eccezionali (la fatturazione è guidata dal cron, non da Stripe). Nel vostro dashboard Stripe: Sviluppatori → Webhook → Aggiungi un endpoint, con l’URL mostrato nella configurazione del modulo (della forma https://vostronegozio.it/module/dfsubscription/webhook), e iscrivetevi a questi tre eventi:

• payment_method.detached — carta eliminata su Stripe: l’abbonamento passa a «pagamento fallito» per avvisarvi prima della scadenza.
• charge.dispute.created — contestazione (chargeback): registrata sull’abbonamento interessato.
• charge.refunded — rimborso: registrato sull’abbonamento interessato.

Copiate poi il segreto di firma (whsec_...) fornito da Stripe nel campo corrispondente della configurazione.

Configurazione del cron

Il cron è il motore dei rinnovi: ogni giorno rileva gli abbonamenti in scadenza, addebita le carte memorizzate e crea gli ordini. L’URL protetto da token è mostrato nella configurazione e nel dashboard del modulo, della forma:

https://vostronegozio.it/module/dfsubscription/cron?token=VOSTRO_TOKEN

Create un cron job giornaliero presso il vostro hosting (cPanel, Plesk, crontab) che chiami questo URL. Esempio di crontab per un’esecuzione ogni giorno alle 6:00:

0 6 * * * curl -s "https://vostronegozio.it/module/dfsubscription/cron?token=VOSTRO_TOKEN" > /dev/null 2>&1

Creare piani di abbonamento

I piani si gestiscono direttamente dalla scheda prodotto del back office: Catalogo → Prodotti → il vostro prodotto → scheda Moduli / DataFirefly Subscriptions. Per ogni piano, definite:

• Frequenza di fatturazione — settimanale, quindicinale, mensile, trimestrale, semestrale o annuale.
• Frequenza di consegna — uguale alla fatturazione, settimanale, quindicinale o mensile. Esempio: fatturazione mensile + consegna settimanale = box settimanale con pagamento mensile.
• Sconto (%) — la riduzione concessa agli abbonati rispetto al prezzo di acquisto singolo. Viene mostrata nella scheda prodotto e applicata anche a ogni rinnovo.
• Impegno minimo — numero di cicli prima che la disdetta sia possibile (0 = disdetta libera).
• Cicli massimi — per abbonamenti a durata limitata (0 = illimitato).
• Giorni di prova — periodo di prova prima della prima fatturazione.

Un prodotto può offrire più piani (es. mensile -10 % e annuale -20 %): il cliente sceglie nel blocco «Abbonati e risparmia» della scheda prodotto.

Percorso del cliente

Scheda prodotto

Un blocco a scomparsa presenta i piani disponibili con i loro prezzi scontati. Il cliente seleziona il suo piano (la selezione è salvata in database, affidabile anche se cambia dispositivo) e aggiunge al carrello normalmente.

Checkout e pagamento

Al passaggio di pagamento, l’opzione «Paga con carta e attiva il mio abbonamento» appare se il carrello contiene solo prodotti in abbonamento e il cliente è connesso. Il modulo carta sicuro di Stripe viene mostrato direttamente nella pagina:

1. Il cliente inserisce la sua carta; il 3D Secure si attiva automaticamente se la sua banca lo richiede.
2. Il pagamento copre il totale esatto del carrello, spedizione inclusa.
3. La carta viene memorizzata su Stripe per i cicli successivi (card on file, con consenso conforme SCA).
4. Il modulo ri-verifica lato server lo stato e l’importo del pagamento prima di creare l’ordine — il browser non viene mai creduto sulla parola.

Rinnovi

A ogni esecuzione del cron, per ogni abbonamento in scadenza:

1. Il modulo ricostruisce un vero carrello PrestaShop: prodotto, combinazione, indirizzo e corriere originali.
2. Lo sconto del piano viene applicato tramite una regola carrello automatica monouso.
3. Il totale esatto è calcolato dal motore prezzi nativo — tasse e spedizione incluse se l’opzione «Spedizione sui rinnovi» è attivata (lo è di default).
4. La carta memorizzata viene addebitata off-session per esattamente quell’importo.
5. Viene creato un ordine PrestaShop standard, con lo stato ordine di vostra scelta (configurabile, es. uno stato dedicato «Rinnovo»).
6. Il cliente riceve l’email di conferma del rinnovo; l’evento viene registrato.

Ogni ordine di rinnovo è visibile in Ordini come qualsiasi vendita, con la sua transazione Stripe associata — le vostre esportazioni contabili e la gestione del magazzino funzionano senza modifiche.

Dunning: gestione dei pagamenti falliti

Quando un addebito di rinnovo fallisce (carta scaduta, limite, rifiuto bancario):

1. L’abbonamento passa allo stato «pagamento fallito» e il cliente riceve immediatamente un’email di promemoria che lo invita ad aggiornare la sua carta.
2. Il cron riprova automaticamente il pagamento — di default 3 tentativi ogni 3 giorni, entrambi i valori configurabili.
3. Dopo il numero configurato di fallimenti consecutivi, l’abbonamento viene annullato automaticamente e il cliente ne viene informato.

Ogni tentativo e il suo risultato vengono registrati nei log dell’abbonamento. In pratica, il dunning recupera dal 50 al 70 % dei pagamenti che sarebbero andati persi.

Area cliente «I miei abbonamenti»

Accessibile dall’account cliente, quest’area elenca gli abbonamenti con il loro stato, la prossima data di fatturazione e di consegna. Secondo le vostre impostazioni, il cliente può:

• Mettere in pausa / riprendere — le date vengono ricalcolate alla ripresa.
• Saltare il prossimo ciclo — fatturazione e consegna vengono posticipate insieme di un periodo.
• Disdire — liberamente, o solo dopo l’impegno minimo del piano. Alla disdetta, la carta memorizzata viene scollegata automaticamente su Stripe e viene inviata un’email di conferma.

Ogni azione richiede una conferma e segue il pattern POST-redirect-GET: nessun doppio invio possibile, messaggi di conferma nativi PrestaShop.

Back office

• Dashboard — MRR, abbonamenti attivi, tasso di churn, pagamenti falliti, URL di cron e webhook pronti da copiare.
• Abbonamenti — elenco filtrabile per stato, frequenza e cliente; vista dettagliata con la cronologia degli ordini generati e i log, e link diretti all’ordine e alla scheda cliente.
• Piani — panoramica di tutti i piani esistenti (la creazione avviene dalla scheda prodotto).
• Log — tutti gli eventi con marca temporale: creazioni, rinnovi, fallimenti, tentativi, pause, disdette, webhook ricevuti.

FAQ tecnica e risoluzione dei problemi

L’opzione di pagamento non appare al checkout

• Verificate che il carrello contenga solo prodotti con un piano selezionato e che il cliente sia connesso.
• Verificate che le chiavi Stripe della modalità attiva siano inserite.
• Se avete appena migrato da una versione 1.x: reinstallate il modulo o rilanciate l’aggiornamento — le restrizioni valute/paesi/corrieri vengono aggiunte dagli script di migrazione 2.x e sono indispensabili perché l’opzione appaia.

I rinnovi non si attivano

• Verificate che il cron job sia pianificato e che il suo URL contenga il token corretto (provate l’URL in un browser: deve rispondere con un riepilogo JSON).
• Consultate la scheda Log: ogni esecuzione del cron vi lascia una traccia.

Un pagamento 3DS resta «in attesa»

Se il cliente chiude la pagina durante l’autenticazione 3D Secure, non avviene alcun addebito e non viene creato alcun ordine. Può semplicemente riordinare; il pagamento precedente scadrà da solo su Stripe.

Come testare il percorso completo?

1. Mettete il modulo in modalità test e inserite le chiavi pk_test/sk_test.
2. Create un piano su un prodotto e fate un ordine con la carta 4242 4242 4242 4242 (o 4000 0027 6000 3184 per forzare una sfida 3DS).
3. Nel database, spostate la data next_billing_date dell’abbonamento a ieri, poi chiamate l’URL del cron: deve apparire un ordine di rinnovo.
4. Per testare il dunning, usate la carta 4000 0000 0000 0341 (fallimento all’addebito off-session).