Addebito diretto SEPA con mandato online: documentazione del modulo PrestaShop
Installare, configurare e usare il modulo di addebito diretto SEPA: mandato firmato online con prova sigillata, file pain.008 validato, piani ricorrenti, respingimenti e GDPR.
Presentazione
Il modulo dfsepadebit aggiunge l’addebito diretto SEPA come metodo di pagamento a PrestaShop 1.7.8, 8 e 9. Il cliente firma un mandato online durante l’ordine, con un codice ricevuto via e-mail, senza lasciare la pagina di pagamento. Ogni ordine, ogni rata di un piano e ogni addebito singolo diventa un addebito pre-notificato al cliente. Lei genera il file pain.008 e lo carica sul portale della sua banca. Poi importa i file di ritorno per aggiornare pagamenti e respingimenti.
Il modulo non si collega alla banca e non trasmette dati a terzi: i fondi arrivano direttamente sul suo conto.

Novità della 2.0.0: firma online corretta (nella 1.1.0 non funzionava con PrestaShop 8 e 9), compatibilità con PrestaShop 1.7.8, mandati singoli (OOFF), sequenza FNAL, pain.008.001.08 come predefinito, validazione di ogni file con lo schema ufficiale ISO 20022, PDF del mandato sigillato e traccia di controllo concatenata, file bancari cifrati e mai inviati via e-mail, permessi per profilo dipendente, assistente di avvio e configurazione in 5 schede.
Requisiti
- Identificativo del creditore SEPA e contratto per l’emissione di addebiti diretti SEPA, da richiedere alla sua banca. Specifichi lo schema B2B se addebita imprese.
- Il formato di file accettato dalla banca (pain.008.001.08 o pain.008.001.02) e il suo termine di presentazione (di solito 1 giorno lavorativo TARGET prima della data di addebito).
- Un negozio con l’euro attivato: il metodo di pagamento compare solo per carrelli in euro.
- PrestaShop da 1.7.8 a 9.x, PHP da 7.1 a 8.5 con l’estensione OpenSSL (cifratura AES-256-GCM degli IBAN e dei file).
- Un’attività cron giornaliera (hosting o servizio esterno) per piani ricorrenti, file automatici e conferme di pagamento.
Installazione e aggiornamento
- In Moduli > Gestione moduli, clicchi su Carica un modulo e selezioni
dfsepadebit-2.0.0.zip. - Il modulo crea le sue tabelle, due stati d’ordine («Addebito diretto SEPA programmato» e «Addebito diretto SEPA respinto») e il menu Vendi > Addebito diretto SEPA: Cruscotto, Mandati, Addebiti, Piani ricorrenti e File bancari.
- Apra la configurazione. L’assistente di avvio in alto indica cosa manca: nome e indirizzo completo del creditore, identificativo del creditore, IBAN, euro attivato, attività giornaliera, primo file accettato dalla banca. Finché il creditore non è completo, il metodo di pagamento resta nascosto.
- Copi l’URL di cron mostrato nella configurazione e lo programmi una volta al giorno. Il pulsante Nuovo URL di cron ne genera un altro e invalida il precedente.

Aggiornamento dalla 1.1.0: carichi il nuovo ZIP sopra il precedente. Mandati, addebiti, piani, file bancari e impostazioni vengono conservati, compreso il formato pain.008.001.02 se lo aveva scelto. L’aggiornamento ricalcola le impronte degli IBAN, cifra i file già generati, apre la traccia di controllo di ogni mandato e rinomina gli stati d’ordine che avevano ancora il nome originale. I mandati firmati con la 1.1.0 non hanno PDF sigillato: il loro PDF viene rigenerato dalla prova originale, con l’indicazione di copia rigenerata.
Configurazione
La configurazione è suddivisa in 5 schede.
Creditore
Nome del creditore (come comparirà negli estratti conto dei clienti), identificativo del creditore, IBAN del conto accreditato, BIC (facoltativo nel SEE) e indirizzo completo: via, CAP, città e paese sono obbligatori perché compaiono sul mandato. L’identificativo è controllato con il suo codice di controllo (MOD 97-10) e l’IBAN con il suo codice di controllo e la lunghezza del paese.
Mandati e checkout
- Schema dei nuovi mandati: SEPA B2B (tra imprese, nessun diritto di rimborso, il debitore deve registrare il mandato presso la sua banca) o SEPA Core (qualsiasi cliente, rimborso possibile entro 8 settimane).
- Tipo di pagamento dei mandati firmati online: ricorrente (il cliente firma una volta e il mandato vale per gli ordini e i piani successivi) o singolo (un mandato per ordine, valido per un solo addebito).
- Prefisso dei riferimenti di mandato: lettere e cifre, massimo 8 caratteri (DF predefinito).
- Firma con un codice inviato via email: consigliata, rafforza il fascicolo di prova. Se disattivata, il cliente firma con una semplice casella.
- Allegare il PDF del mandato all’e-mail di conferma: la copia allegata mostra l’IBAN parzialmente nascosto. La copia completa resta disponibile nell’account cliente.
- Solo per clienti con ragione sociale: il metodo di pagamento è proposto solo se l’indirizzo di fatturazione contiene un’azienda.
- Gruppi di clienti autorizzati, importi minimo e massimo dell’ordine.
- Esposizione massima per cliente: addebiti non ancora pagati più il carrello in corso. Oltre questa soglia il metodo di pagamento è nascosto per il cliente.
- Nascondi dopo respingimenti negli ultimi 12 mesi: 2 predefinito, 0 per disattivare.
Addebiti e file bancari
- Termine di pre-notifica: i rulebook fissano 14 giorni di calendario, salvo un termine diverso concordato con il debitore. Il modulo propone 2 giorni: un termine inferiore a 14 giorni deve essere indicato nelle sue condizioni di vendita. Il termine è riportato nel testo del mandato. Un ordine viene addebitato alla fine di questo termine.
- Termine di presentazione della sua banca, in giorni lavorativi TARGET.
- Formato del file: pain.008.001.08 predefinito (versione 2019 di ISO 20022, usata dalle linee guida di implementazione EPC in vigore). Mantenga pain.008.001.02 solo se la banca lo richiede ancora.
- Contabilizzazione cumulativa: un solo accredito per file sull’estratto conto, oppure un accredito per addebito.
- Invia il primo addebito di un mandato come FRST: il rulebook ammette RCUR dal primo addebito; mantenga FRST se la banca lo richiede ancora.
- Inviare l’ultimo addebito di un piano limitato come FNAL: facoltativo. Dopo un addebito FNAL il mandato è chiuso e non può più essere usato.
- Includere sempre l’indirizzo del debitore nel file: l’indirizzo è sempre inviato per i conti fuori dal SEE; attivi l’opzione se la banca lo chiede per ogni addebito.
- Genera il file bancario automaticamente: l’attività giornaliera crea il file degli addebiti in scadenza entro N giorni e invia un avviso all’indirizzo degli avvisi. Il file non viene mai inviato via e-mail: lo scarica dal back office.
- Segna come pagato automaticamente dopo N giorni senza respingimento (5 predefinito). 0 per confermare a mano o con camt.054.
Respingimenti
- Codici motivo con nuovo tentativo automatico: AM04 e MS03 predefiniti.
- Numero massimo di nuovi tentativi e attesa prima di un nuovo tentativo.
- Spese di respingimento aggiunte al nuovo tentativo, solo se le condizioni di vendita lo prevedono.
- Codici motivo che revocano il mandato: AC01, AC04, AC06, AC13, MD01 e MD07 predefiniti. Il mandato viene chiuso e i suoi piani annullati.
- Email per gli avvisi al commerciante: respingimenti, revoche, cambi di banca, piani sospesi e file automatici. Email del negozio se vuoto.
Dati e privacy
- Conservare i mandati chiusi dopo l’ultimo addebito: minimo 13 mesi (vedi GDPR più sotto).
- Elimina tutti i dati alla disinstallazione: disattivato per impostazione predefinita. I mandati sono prove; eliminarli può violare i suoi obblighi di conservazione.
Percorso del cliente
Firma nel checkout
Al passaggio di pagamento, il cliente sceglie l’addebito diretto SEPA. Il blocco mostra l’importo e la data di addebito. Se ha già un mandato attivo, seleziona il suo conto (IBAN mascherato) e conferma l’ordine.
Altrimenti firma un nuovo mandato in 3 passaggi all’interno del blocco di pagamento. Il modulo è precompilato con l’indirizzo di fatturazione: azienda, titolare, indirizzo, luogo di firma (la città), IBAN e BIC. L’IBAN viene formattato e verificato durante la digitazione: lunghezza del paese, codice di controllo, BIC obbligatorio fuori dal SEE. Il cliente legge il testo del mandato (comprimibile) e spunta l’accettazione. In B2B conferma anche che il conto è aziendale e che registrerà il mandato presso la sua banca.

Riceve via e-mail un codice di 6 cifre valido 10 minuti. Può chiedere un nuovo codice dopo 45 secondi; dopo 5 errori deve chiederne un altro. Il mandato è firmato non appena viene inserito il codice corretto. Fino ad allora la conferma dell’ordine è bloccata con un messaggio.


La pagina di conferma riporta l’importo, la data di addebito, l’IBAN mascherato, il riferimento del mandato e l’identificativo del creditore.

Se il tema impedisce l’esecuzione dello script, dopo la conferma il cliente viene reindirizzato alla pagina di firma autonoma, poi l’ordine viene creato. Non è possibile creare due volte un ordine per lo stesso carrello e l’importo viene sempre ricalcolato dal server a partire dal carrello.
E-mail di conferma e PDF del mandato
Il cliente riceve la conferma del mandato con l’IBAN mascherato e un link ai suoi mandati. Se l’opzione è attiva, anche la copia PDF allegata ha l’IBAN mascherato.

Il PDF riporta i dati del mandato SEPA: titolo «SEPA Business to Business Direct Debit Mandate» in B2B o «SEPA Direct Debit Mandate» in Core, riferimento univoco, identificativo e indirizzo del creditore, debitore, conto, tipo di pagamento (ricorrente o singolo), testo di autorizzazione, luogo e data di firma, metodo di firma e impronta SHA-256.

Pagina di firma autonoma
Quando invia una richiesta di firma dal back office, il cliente riceve un link sicuro a una pagina di firma, senza bisogno di accedere. La pagina mostra il riepilogo del creditore e gli stessi controlli del checkout.

Account cliente
La pagina I miei mandati SEPA presenta ogni mandato in una scheda: PDF, piani in corso e ultimi addebiti. Il cliente può revocare un mandato o cliccare su Cambia conto bancario: firma un nuovo mandato, i suoi piani e gli addebiti non ancora inviati passano al nuovo conto e il vecchio mandato viene chiuso. Il link compare in Il mio account solo per i clienti dei gruppi autorizzati o che hanno già un mandato. Il dettaglio di ogni ordine mostra la data di addebito e il suo stato.

Back office
Cruscotto
Importo da inviare alla banca entro 7 giorni, importo in banca in attesa di conferma, incassato nel mese, tasso di respingimento a 90 giorni, ricavi ricorrenti mensili dei piani a importo fisso, mandati attivi e in attesa. Un grafico mostra le prossime 6 settimane (addebiti creati e previsione dei piani). Gli ultimi respingimenti e i mandati in attesa di firma, con un pulsante Sollecita, completano la pagina. Compare un avviso se l’attività giornaliera non è stata eseguita da 36 ore.

Mandati
L’elenco mostra il riferimento, il debitore, l’IBAN mascherato, lo schema (B2B o Core), il tipo (ricorrente o singolo) e lo stato. Il pulsante Nuovo mandato offre due modalità: inviare al cliente una richiesta di firma online oppure registrare un mandato cartaceo già firmato con luogo e data di firma. Il campo Sostituisce il mandato trasferisce i piani di un mandato esistente una volta firmato il nuovo.

La scheda di un mandato mostra le prove di firma (data, metodo, luogo, indirizzo IP, browser, impronta della prova), il PDF sigillato con il suo SHA-256, i piani, gli addebiti e la traccia di controllo cronologica con il controllo di integrità. Il pulsante Visualizzare l’IBAN completo richiede il permesso di modifica e ogni visualizzazione viene registrata. Anche la scheda cliente del back office mostra un blocco Mandati SEPA con un pulsante per richiedere un nuovo mandato.

Addebiti
Elenco filtrabile di tutti gli addebiti con il loro stato: da esportare, inviato alla banca, pagato, respinto, annullato. Dalla scheda di un addebito: segnare come pagato, registrare un respingimento con il suo codice, annullare (prima dell’esportazione). Dopo un respingimento con un codice di nuovo tentativo, la scheda mostra il nuovo tentativo programmato e lo storico. Il pulsante Nuovo addebito singolo crea un addebito su un mandato attivo, eventualmente collegato a un ordine. Un importo nullo è rifiutato e un mandato singolo accetta un solo addebito.

Piani ricorrenti
Un piano è collegato a un mandato ricorrente (attivo o in attesa di firma) e funziona in due modalità: importo fisso o ripetere un ordine (l’ordine di riferimento viene ripetuto ai prezzi del giorno a ogni scadenza, poi addebitato). Scelga la frequenza, la prossima scadenza e il numero di addebiti (0 per nessuna fine). Il cliente riceve un’e-mail di riepilogo. Un piano può essere sospeso, ripreso o interrotto.
File bancari
- Scelga la data limite degli addebiti da includere e clicchi su Anteprima: non viene esportato nulla. L’anteprima mostra un blocco di pagamento per schema, sequenza (FRST, RCUR, OOFF, FNAL) e data, e le date anticipate per rispettare il termine della banca.
- Clicchi su Genera. Il file viene validato con lo schema ufficiale ISO 20022 prima di essere salvato, poi conservato cifrato con la sua impronta SHA-256. L’elenco indica l’esito della validazione e il numero di download.
- Scarichi il file e lo carichi lo stesso giorno sul portale della banca. Il modulo non invia mai nulla a una banca.
- Importi poi i file di ritorno: pain.002 (file o transazioni respinti), camt.054 o camt.053 (storni e accrediti). Lo stesso file importato due volte non viene rielaborato.

Un file non ancora inviato può essere annullato: i suoi addebiti tornano «da esportare». La generazione è bloccata: due clic, due dipendenti o un’attività giornaliera simultanea non possono esportare due volte gli stessi addebiti.
Pagina dell’ordine
La pagina dell’ordine nel back office mostra un blocco addebito SEPA: mandato, IBAN mascherato, importo, scadenza e stato di ogni addebito.

Ciclo di un addebito
- Da esportare: creato con l’ordine, da un piano o a mano. Il cliente riceve la pre-notifica. L’ordine è in «Addebito diretto SEPA programmato».
- Inviato alla banca: incluso in un file. La data può essere spostata al primo giorno possibile secondo il calendario TARGET e il termine di presentazione.
- Pagato: dopo il termine senza respingimento, all’importazione di un camt.054 o a mano. L’ordine passa a «Pagamento accettato».
- Respinto: codice motivo registrato, ordine in «Addebito diretto SEPA respinto», nuovo tentativo o revoca secondo la configurazione.
Sequenze
- FRST: primo addebito di un mandato ricorrente, se l’opzione è attiva. Un solo primo addebito per mandato e per file; se viene respinto, il tentativo successivo riparte come FRST.
- RCUR: addebiti successivi di un mandato ricorrente.
- OOFF: addebito unico di un mandato singolo. Un nuovo tentativo dopo un respingimento è trattato come lo stesso pagamento; se necessario, faccia confermare questa prassi dalla banca.
- FNAL: ultimo addebito di un piano limitato, se l’opzione è attiva. Il mandato viene chiuso dopo il pagamento.
Un mandato non utilizzato per alcun addebito per 36 mesi decade.
Gestione dei respingimenti
| Codice | Significato | Azione predefinita |
|---|---|---|
| AM04 | Fondi insufficienti | Nuovo tentativo |
| MS03 | Motivo non specificato dalla banca | Nuovo tentativo |
| AC01, AC04, AC06 | Conto errato, chiuso o bloccato | Revoca del mandato |
| AC13 | Conto di un consumatore in B2B | Revoca del mandato |
| MD01 | Nessun mandato valido (spesso un mandato B2B non registrato in banca) | Revoca del mandato |
| MD07 | Debitore deceduto | Revoca del mandato |
| MS02, MD06 | Rifiuto o rimborso richiesto dal debitore | Avviso, gestione manuale |
Un rifiuto del file o di un blocco di pagamento in un pain.002 (formato, identificativo del creditore non riconosciuto…) non riguarda il cliente: gli addebiti tornano «da esportare» per il file successivo.
Prova di firma e traccia di controllo
- Istantanea di prova: al momento della firma il modulo registra un’istantanea con data e ora che contiene il testo esatto del mandato e la sua impronta, lo schema, il tipo di pagamento, il luogo, l’indirizzo IP, il browser, il metodo di firma, l’IBAN mascherato e la sua impronta. L’IBAN completo non vi compare mai.
- PDF sigillato: il PDF del mandato viene prodotto una sola volta, alla firma, poi conservato cifrato. Il suo SHA-256 è registrato sul mandato e nella traccia di controllo; i download successivi restituiscono esattamente quel file.
- Traccia di controllo: creazione, invio ed errori del codice, firma, PDF sigillato, e-mail, visualizzazioni dell’IBAN completo, download, addebiti, esportazioni, pagamenti, respingimenti, revoca e anonimizzazione. Gli eventi di ogni mandato sono concatenati con SHA-256: una riga modificata o eliminata viene segnalata nella scheda del mandato.
Il codice monouso inviato via e-mail è una firma elettronica ai sensi dell’articolo 3, punto 10, del regolamento eIDAS (UE) n. 910/2014; non è una firma qualificata. Il modulo non garantisce alcun valore giuridico particolare: la sua efficacia probatoria e la sua accettazione da parte della banca sono da valutare con i suoi consulenti.
Sicurezza e permessi dei dipendenti
- IBAN dei mandati e file bancari cifrati con AES-256-GCM, con una chiave derivata dalla chiave segreta del negozio (file dei parametri, non il database). Conservi questo file in caso di migrazione: senza di esso IBAN e file bancari non sono più leggibili.
- I duplicati vengono individuati con un’impronta HMAC-SHA256, mai con l’IBAN in chiaro.
- Scaricare un file bancario o il PDF completo, visualizzare l’IBAN completo, inviare di nuovo un link di firma o eseguire le attività richiede il permesso di modifica sulla scheda interessata. Un profilo in sola lettura ottiene una copia del PDF con l’IBAN mascherato e non può scaricare i file bancari.
- In multinegozio, un dipendente vede solo mandati, addebiti, piani e file dei negozi del suo contesto.
- Lato negozio, un mandato è accessibile solo al suo titolare, nel suo negozio, con un token contro la falsificazione delle richieste per la revoca e il PDF.
- I file di ritorno importati vengono letti senza entità esterne (protezione XXE).
Attività giornaliera (cron)
L’URL di cron, protetto da un token, crea gli addebiti dei piani in scadenza entro il termine di pre-notifica, genera il file automatico se attivato, segna come pagati gli addebiti senza respingimento dopo il termine configurato, fa decadere i mandati inutilizzati da 36 mesi ed elimina le firme abbandonate da 60 giorni. Due esecuzioni simultanee non possono sovrapporsi. Il pulsante Esegui ora le attività della pagina File bancari fa lo stesso per il negozio corrente.
E-mail inviate
- Al cliente: codice di firma, conferma del mandato, richiesta di firma, avviso di piano, pre-notifica dell’addebito, respingimento.
- Al commerciante: respingimento, revoca da parte del cliente, cambio di banca, piano sospeso, file automatico pronto (con il link al back office, senza file allegato).
Gli 8 modelli sono forniti in 8 lingue, in HTML e testo, in mails/, e si modificano come le e-mail native. Nessuna e-mail contiene un IBAN completo o un file bancario.
Fattura, scheda ordine e GDPR
La fattura PDF riporta una nota di pre-notifica (importo, data, IBAN mascherato, riferimento del mandato, identificativo del creditore), che diventa «pagato il» una volta confermato l’addebito.
Con il modulo GDPR ufficiale, i mandati (IBAN mascherato) e gli addebiti sono inclusi nell’esportazione dei dati. A una richiesta di cancellazione vengono anonimizzati solo i mandati in attesa e i mandati chiusi il cui ultimo addebito supera il periodo di conservazione configurato: IBAN, e-mail, indirizzo e PDF sigillato vengono allora eliminati. Gli altri mandati sono conservati come prova e lei riceve un avviso.
Periodo di conservazione: i rulebook EPC rinviano al diritto nazionale e impongono come minimo il periodo di rimborso di un’operazione non autorizzata, cioè 13 mesi dopo la data di addebito. Il diritto nazionale, in particolare contabile, può imporre di più: lo stabilisca con i suoi consulenti. Il modulo non fissa alcun periodo nazionale e rifiuta un valore inferiore a 13 mesi.
Limiti
- Il modulo produce file pain.008 e legge file pain.002, camt.054 e camt.053. Non trasmette nulla a una banca e non offre connessione EBICS né prestatore di pagamento.
- Non garantisce la conformità legale del suo utilizzo: verifichi con la banca formato, termini, BIC, indirizzo e uso di FRST, e con i suoi consulenti le condizioni di vendita, il termine di pre-notifica e il periodo di conservazione.
- Sono considerate solo le festività TARGET comuni: 1° gennaio, Venerdì santo, Lunedì dell’Angelo, 1° maggio, 25 e 26 dicembre.
- I paesi aggiunti di recente dall’EPC (Albania, Moldavia, Montenegro, Macedonia del Nord, Serbia) sono accettati con BIC obbligatorio; l’effettiva partecipazione di ciascuna banca non viene verificata.
Risoluzione dei problemi
Il metodo di pagamento non compare
Verifichi l’assistente di avvio (creditore completo con indirizzo), che il carrello sia in euro, che il cliente abbia effettuato l’accesso (non ospite), che l’indirizzo di fatturazione abbia un’azienda se l’opzione è attiva, che il cliente appartenga a un gruppo autorizzato e che non abbia superato l’esposizione o il numero di respingimenti consentiti.
Respingimento MD01 su un mandato B2B
Il cliente non ha registrato il mandato presso la sua banca. Gli chieda di farlo con il riferimento del mandato e il suo identificativo del creditore, poi crei un nuovo addebito singolo.
Il cliente non riceve il codice
Verifichi la configurazione e-mail di PrestaShop e la cartella spam del cliente. Un nuovo codice può essere richiesto dopo 45 secondi; è valido 10 minuti.
La banca rifiuta il file
Verifichi il formato atteso (pain.008.001.08 o .02), il BIC e l’indirizzo del debitore. Un file che non rispetta lo schema ISO 20022 non viene mai salvato: il messaggio mostrato alla generazione cita i primi errori. Se la colonna dello schema indica «Non verificato», sul server mancano le estensioni PHP DOM o libxml.
«Traccia di controllo alterata»
Una riga della traccia di controllo del mandato è stata modificata o eliminata direttamente nel database. Il messaggio indica l’evento a partire dal quale la catena non è più integra. Ripristini la tabella da un backup.