Costi di Pagamento (dfpaymentfees) — Guida completa

Presentazione

DataFirefly Costi di Pagamento consente di applicare costi aggiuntivi a ogni metodo di pagamento del tuo negozio PrestaShop 8 o 9. L’obiettivo è duplice: trasferire il costo reale di un metodo di pagamento (commissioni sulle carte, gestione del contrassegno, trattamento di assegni o bonifici) e orientare i clienti verso i metodi di pagamento più vantaggiosi per il tuo negozio.

Il modulo si basa su un motore di regole: ogni regola combina un importo fisso e/o una percentuale, una base di calcolo, limiti, una soglia di gratuità e un insieme di condizioni (gruppo clienti, paese, valuta, totale del carrello). I costi vengono mostrati al cliente durante il checkout e poi aggiunti automaticamente all’ordine alla convalida.

Installazione

1. Nel back office di PrestaShop, vai su Moduli → Gestore moduli → Carica un modulo.
2. Seleziona il file dfpaymentfees.zip scaricato dal tuo account DataFirefly.
3. Fai clic su Installa e poi su Configura.
4. Svuota la cache di PrestaShop (Parametri avanzati → Prestazioni → Svuota la cache).
5. Dalla pagina di configurazione, fai clic su Gestisci le regole di costo per creare la tua prima regola.

Parametri generali

La pagina di configurazione del modulo (Moduli → Gestore moduli → Costi di Pagamento → Configura) contiene due impostazioni globali:

• Mostrare i costi al checkout — mostra l’importo dei costi accanto a ogni metodo di pagamento durante l’ordine. Disattiva questa opzione se preferisci applicare i costi solo al momento della convalida, senza annunciarli nell’elenco dei metodi di pagamento.
• Etichetta dei costi — etichetta predefinita mostrata al cliente e sull’ordine (ad esempio «Costi di pagamento»). Questo campo è multilingua e può essere sovrascritto per singola regola.

Creare una regola di costo

Da Gestisci le regole di costo, fai clic su Aggiungi una regola di costo. Il modulo è organizzato in quattro blocchi: identificazione, importo, limiti e condizioni.

Identificazione

• Attiva — attiva o disattiva la regola senza eliminarla.
• Etichetta (cliente) — il testo mostrato al cliente al checkout e sull’ordine. Campo multilingua e obbligatorio.
• Metodo di pagamento — il modulo interessato (ad esempio ps_wirepayment, ps_checkpayment, il tuo modulo di carta…), oppure Tutti i metodi di pagamento per una regola generica.
• Priorità — un numero intero. Un valore più basso viene valutato per primo. Vedi «Ordine di valutazione» più avanti.

Importo dei costi

• Costo fisso — un importo fisso aggiunto (ad esempio 1.50).
• Costo percentuale — una percentuale applicata alla base di calcolo (ad esempio 2.5 per 2,5 %).
• Includere le spese di spedizione nella base % — se attivo, la percentuale si applica ai prodotti e alle spese di spedizione; altrimenti solo ai prodotti.
• Base di calcolo IVA inclusa — scegli se la percentuale viene calcolata sul totale IVA inclusa o IVA esclusa.

I due importi sono cumulabili. La formula applicata è:

costo = costo_fisso + (base × costo_percentuale / 100)

Limiti e gratuità

• Costo minimo — se il calcolo restituisce un importo inferiore, viene applicato questo minimo. 0 = nessun minimo.
• Costo massimo — limita l’importo dei costi. 0 = nessun massimo.
• Soglia di gratuità — se il totale IVA inclusa del carrello raggiunge questo importo, non viene applicato alcun costo. 0 = disattivata.

Condizioni di applicazione

Quattro famiglie di condizioni permettono di definire con precisione quando la regola si applica. Un elenco lasciato vuoto significa «nessuna restrizione» su quel criterio.

• Gruppi clienti — la regola si applica solo se il cliente appartiene a uno dei gruppi selezionati. Tipicamente: applicare i costi ai privati ed esentare i professionisti.
• Paesi — basato sul paese dell’indirizzo di fatturazione del carrello.
• Valute — la regola si applica solo alle valute selezionate.
• Totale carrello minimo / massimo — la regola si applica solo se il totale IVA inclusa del carrello rientra in questo intervallo. 0 disattiva il limite corrispondente.

In multinegozio, un campo aggiuntivo Negozi permette di associare la regola a uno o più negozi. Lasciandolo vuoto, la regola viene associata a tutti i negozi.

Ordine di valutazione delle regole

Per un dato metodo di pagamento, il modulo recupera tutte le regole attive che riguardano quel modulo (o «Tutti»), ordinate per priorità crescente e poi per identificativo. Valuta le condizioni di ogni regola in quest’ordine e applica la prima regola le cui condizioni siano tutte soddisfatte. Le regole successive vengono ignorate.

Caso particolare della soglia di gratuità: se una regola corrisponde ma il carrello raggiunge la sua soglia di gratuità, non viene applicato alcun costo — e il modulo non valuta le regole successive. La gratuità è quindi una decisione definitiva, non un semplice «passaggio alla regola successiva».

Gestione dell’IVA

Due impostazioni determinano il trattamento fiscale dei costi:

• Importi inseriti IVA inclusa — indica se gli importi che hai inserito (costo fisso, limiti) includono già l’IVA.
• Regola fiscale — la regola fiscale di PrestaShop applicata ai costi. Seleziona Nessuna imposta per costi senza IVA.

Il modulo calcola l’aliquota applicabile a partire dalla regola fiscale e dall’indirizzo di fatturazione del cliente, quindi ne deduce la ripartizione:

• Se gli importi sono inseriti IVA inclusa: IVA esclusa = IVA inclusa / (1 + aliquota).
• Se gli importi sono inseriti IVA esclusa: IVA inclusa = IVA esclusa × (1 + aliquota).

Entrambi i valori, insieme all’aliquota applicata, vengono salvati sull’ordine per la tua contabilità.

Esempio di calcolo

Regola: costo fisso 1,00 € + 2 % del carrello, base IVA inclusa prodotti + spedizione, limite massimo 5,00 €, importi inseriti IVA inclusa, IVA 22 %.

• Carrello: 120,00 € IVA inclusa di prodotti + 5,00 € IVA inclusa di spedizione = base 125,00 €.
• Costo lordo: 1,00 + (125,00 × 2 / 100) = 3,50 € IVA inclusa.
• Sotto il limite di 5,00 €: mantenuto invariato.
• Ripartizione: IVA esclusa = 3,50 / 1,22 = 2,87 €, IVA = 0,63 €.

Visualizzazione lato cliente

Quando l’opzione Mostrare i costi al checkout è attiva, il modulo calcola i costi per ogni metodo di pagamento disponibile e li trasmette al front office. Nella pagina /order:

• L’importo dei costi viene aggiunto accanto all’etichetta di ogni metodo di pagamento interessato.
• Un promemoria appare sotto l’elenco dei metodi di pagamento per l’opzione attualmente selezionata e si aggiorna in tempo reale quando il cliente cambia metodo di pagamento.

Questa visualizzazione è puramente informativa: l’importo effettivamente addebitato viene ricalcolato lato server alla convalida dell’ordine.

Applicazione sull’ordine

Alla convalida dell’ordine (hook actionValidateOrder), il modulo ricalcola i costi per il metodo di pagamento effettivamente utilizzato, quindi:

1. Aggiorna i totali dell’ordine (total_paid, total_paid_tax_incl, total_paid_tax_excl e total_paid_real se pertinente).
2. Aggiorna i totali della fattura se ne esiste già una.
3. Aggiorna l’importo del pagamento registrato, per restare coerente con l’importo incassato.
4. Salva la riga di costo (etichetta, IVA esclusa, IVA inclusa, aliquota) nella tabella df_payment_fee_order.

La riga di costo viene poi mostrata nella pagina di conferma dell’ordine, nel dettaglio ordine lato cliente, nella pagina ordine del back office e aggiunta all’e-mail di conferma.

Una protezione impedisce la doppia elaborazione: se un ordine possiede già una riga di costo, il modulo non fa nulla.

Compatibilità con i gateway di pagamento

• Pagamenti offline (bonifico, assegno, contrassegno, pagamento in negozio): il funzionamento è completo e senza riserve. Il cliente vede i costi, l’ordine e la fattura li includono, e tu incassi l’importo totale mostrato.
• Gateway con reindirizzamento o integrati (PayPal, Stripe, soluzioni bancarie): l’importo trasmesso al gateway è quello calcolato dal modulo di pagamento a partire dal carrello. A seconda del gateway e della sua configurazione, tale importo potrebbe non includere i costi. Verifica il comportamento in ambiente di test prima della messa in produzione.

Per questi ultimi, due approcci sono comuni: riservare le regole di costo ai metodi di pagamento offline, oppure catturare/rettificare l’importo lato gateway. Il nostro supporto può consigliarti in base al gateway utilizzato.

Multinegozio e multilingua

Multinegozio — ogni regola è associata a uno o più negozi tramite il campo Negozi del modulo. Vengono valutate solo le regole associate al negozio corrente. Una regola salvata senza selezione è associata a tutti i negozi.

Multilingua — l’etichetta di ogni regola è traducibile in tutte le lingue attive del negozio. Se l’etichetta non è compilata nella lingua del cliente, il modulo utilizza l’etichetta globale definita nei parametri del modulo.

Risoluzione dei problemi

I costi non compaiono al checkout

• Verifica che l’opzione Mostrare i costi al checkout sia attiva nei parametri del modulo.
• Verifica che la regola sia attiva e che riguardi il metodo di pagamento interessato (o «Tutti»).
• Verifica che il contesto del cliente soddisfi tutte le condizioni: gruppo, paese di fatturazione, valuta, totale del carrello.
• Assicurati che il carrello non raggiunga la soglia di gratuità della regola.
• Svuota la cache di PrestaShop e forza il ricaricamento del browser (Ctrl+F5) per eliminare il vecchio JavaScript.

I costi vengono mostrati ma non aggiunti all’ordine

Il calcolo al checkout e quello alla convalida utilizzano il nome tecnico del modulo di pagamento. Se il tuo modulo di pagamento registra un’etichetta diversa dal nome tecnico, verifica nella tabella df_payment_fee_order che sia stata creata una riga per l’ordine. In caso contrario, crea una regola destinata a Tutti i metodi di pagamento per validare il funzionamento, quindi contatta il supporto indicando il nome del modulo di pagamento utilizzato.

Una regola non si applica mai pur sembrando corretta

Probabilmente una regola con priorità superiore (valore di priorità più basso) corrisponde per prima. Ricorda che viene applicata solo la prima regola corrispondente. Aumenta il valore di priorità delle regole generiche oppure affina le condizioni delle regole concorrenti.

L’importo dell’IVA sembra errato

Verifica la coerenza tra l’impostazione Importi inseriti IVA inclusa e i valori che hai inserito. Un importo inserito IVA inclusa mentre l’impostazione indica IVA esclusa (o viceversa) altera la ripartizione. Verifica inoltre che la regola fiscale selezionata si applichi al paese di fatturazione del cliente.

Il checkout è lento o si blocca

Assicurati di utilizzare la versione 1.0.0 o successiva del modulo, svuota la cache di PrestaShop e forza il ricaricamento del browser (Ctrl+F5) per eliminare una versione di JavaScript in cache.

Disinstallazione

Disinstalla il modulo dal Gestore moduli. La disinstallazione rimuove la scheda di amministrazione, le variabili di configurazione e tutte le tabelle del modulo, compreso lo storico dei costi applicati agli ordini. I totali già registrati sugli ordini esistenti non vengono modificati.