Frais de Paiement (dfpaymentfees) — Guide complet

Présentation

DataFirefly Frais de Paiement permet d’appliquer des frais supplémentaires à chaque moyen de paiement de votre boutique PrestaShop 8 ou 9. L’objectif est double : répercuter le coût réel d’un mode de règlement (commissions carte, gestion du paiement à la livraison, traitement des chèques ou virements) et orienter vos clients vers les moyens de paiement les plus avantageux pour votre boutique.

Le module repose sur un moteur de règles : chaque règle combine un montant fixe et/ou un pourcentage, une base de calcul, des plafonds, un seuil de gratuité, et un ensemble de conditions (groupe de clients, pays, devise, montant de panier). Les frais sont affichés au client pendant le tunnel de commande, puis ajoutés automatiquement à la commande à sa validation.

Installation

1. Dans votre back-office PrestaShop, allez dans Modules → Gestionnaire de modules → Installer un module.
2. Sélectionnez le fichier dfpaymentfees.zip téléchargé depuis votre compte DataFirefly.
3. Cliquez sur Installer puis sur Configurer.
4. Videz le cache PrestaShop (Paramètres avancés → Performance → Vider le cache).
5. Depuis la page de configuration, cliquez sur Gérer les règles de frais pour créer votre première règle.

Paramètres généraux

La page de configuration du module (Modules → Gestionnaire de modules → Frais de Paiement → Configurer) contient deux réglages globaux :

• Afficher les frais dans le checkout — affiche le montant des frais à côté de chaque moyen de paiement pendant la commande. Désactivez cette option si vous préférez n’appliquer les frais qu’au moment de la validation, sans les annoncer dans la liste des moyens de paiement.
• Libellé des frais — libellé par défaut affiché au client et sur la commande (par exemple « Frais de paiement »). Ce champ est multilingue et peut être surchargé règle par règle.

Créer une règle de frais

Depuis Gérer les règles de frais, cliquez sur Ajouter une règle de frais. Le formulaire est organisé en quatre blocs : identification, montant, plafonds et conditions.

Identification

• Active — active ou désactive la règle sans la supprimer.
• Libellé (client) — le texte affiché au client au checkout et sur la commande. Champ multilingue et obligatoire.
• Moyen de paiement — le module concerné (par exemple ps_wirepayment, ps_checkpayment, votre module de carte bancaire…), ou Tous les moyens de paiement pour une règle générique.
• Priorité — un entier. Une valeur plus basse est évaluée en premier. Voir la section « Ordre d’évaluation » ci-dessous.

Montant des frais

• Frais fixe — un montant fixe ajouté (par exemple 1.50).
• Frais en pourcentage — un pourcentage appliqué à la base de calcul (par exemple 2.5 pour 2,5 %).
• Inclure les frais de port dans la base % — si activé, le pourcentage porte sur les produits et les frais de port ; sinon uniquement sur les produits.
• Base de calcul TTC — choisissez si le pourcentage est calculé sur le total TTC ou sur le total HT.

Les deux montants sont cumulables. La formule appliquée est :

frais = frais_fixe + (base × frais_pourcentage / 100)

Plafonds et gratuité

• Frais minimum — si le calcul donne un montant inférieur, ce minimum est appliqué. 0 = pas de minimum.
• Frais maximum — plafonne le montant des frais. 0 = pas de maximum.
• Seuil de gratuité — si le total TTC du panier atteint ce montant, aucun frais n’est appliqué. 0 = désactivé.

Conditions d’application

Quatre familles de conditions permettent de cibler précisément quand la règle s’applique. Une liste laissée vide signifie « aucune restriction » sur ce critère.

• Groupes de clients — la règle ne s’applique que si le client appartient à l’un des groupes sélectionnés. Typiquement : appliquer les frais aux particuliers et en exonérer les professionnels.
• Pays — basé sur le pays de l’adresse de facturation du panier.
• Devises — la règle ne s’applique qu’aux devises sélectionnées.
• Montant panier minimum / maximum — la règle ne s’applique que si le total TTC du panier se situe dans cette fourchette. 0 désactive la borne concernée.

En multiboutique, un champ Boutiques supplémentaire permet d’associer la règle à une ou plusieurs boutiques. Laisser vide associe la règle à toutes les boutiques.

Ordre d’évaluation des règles

Pour un moyen de paiement donné, le module récupère toutes les règles actives qui ciblent ce module (ou « Tous »), triées par priorité croissante puis par identifiant. Il évalue les conditions de chaque règle dans cet ordre et applique la première règle dont toutes les conditions sont satisfaites. Les règles suivantes sont ignorées.

Cas particulier du seuil de gratuité : si une règle correspond mais que le panier atteint son seuil de gratuité, aucun frais n’est appliqué — et le module n’évalue pas les règles suivantes. La gratuité est donc une décision finale, pas un simple « passage à la règle suivante ».

Gestion de la TVA

Deux réglages déterminent le traitement fiscal des frais :

• Montants saisis TTC — indiquez si les montants que vous avez renseignés (frais fixe, plafonds) incluent déjà la TVA ou non.
• Règle de taxe — la règle de taxe PrestaShop appliquée aux frais. Sélectionnez Aucune taxe pour des frais sans TVA.

Le module calcule le taux applicable à partir de la règle de taxe et de l’adresse de facturation du client, puis en déduit la ventilation :

• Si les montants sont saisis TTC : HT = TTC / (1 + taux).
• Si les montants sont saisis HT : TTC = HT × (1 + taux).

Les deux valeurs, ainsi que le taux appliqué, sont enregistrées sur la commande pour votre comptabilité.

Exemple de calcul

Règle : frais fixe 1,00 € + 2 % du panier, base TTC produits + port, plafond max 5,00 €, montants saisis TTC, TVA 20 %.

• Panier : 120,00 € TTC de produits + 5,00 € TTC de port = base 125,00 €.
• Frais bruts : 1,00 + (125,00 × 2 / 100) = 3,50 € TTC.
• Sous le plafond de 5,00 € : conservé tel quel.
• Ventilation : HT = 3,50 / 1,20 = 2,92 €, TVA = 0,58 €.

Affichage côté client

Lorsque l’option Afficher les frais dans le checkout est activée, le module calcule les frais pour chaque moyen de paiement disponible et les transmet au front-office. Sur la page /order :

• Le montant des frais est ajouté à côté du libellé de chaque moyen de paiement concerné.
• Un rappel s’affiche sous la liste des moyens de paiement pour l’option actuellement sélectionnée, et se met à jour en temps réel lorsque le client change de moyen de paiement.

L’affichage est purement informatif : le montant réellement facturé est recalculé côté serveur à la validation de la commande.

Application sur la commande

À la validation de la commande (hook actionValidateOrder), le module recalcule les frais pour le moyen de paiement effectivement utilisé, puis :

1. Met à jour les totaux de la commande (total_paid, total_paid_tax_incl, total_paid_tax_excl, et total_paid_real le cas échéant).
2. Met à jour les totaux de la facture si une facture existe déjà.
3. Met à jour le montant du paiement enregistré, pour rester cohérent avec le montant encaissé.
4. Enregistre la ligne de frais (libellé, HT, TTC, taux) dans la table df_payment_fee_order.

La ligne de frais est ensuite affichée sur la page de confirmation de commande, dans le détail de commande côté client, sur la page commande du back-office, et ajoutée à l’e-mail de confirmation.

Une protection empêche le double traitement : si une commande possède déjà une ligne de frais, le module ne fait rien.

Compatibilité avec les passerelles de paiement

• Paiements hors ligne (virement, chèque, paiement à la livraison, paiement en magasin) : le fonctionnement est complet et sans réserve. Le client voit les frais, la commande et la facture les incluent, et vous encaissez le montant total affiché.
• Passerelles à redirection ou embarquées (PayPal, Stripe, solutions bancaires) : le montant transmis à la passerelle est celui calculé par le module de paiement à partir du panier. Selon votre passerelle et sa configuration, ce montant peut ne pas inclure les frais. Vérifiez le comportement en environnement de test avant la mise en production.

Pour ces dernières, deux approches sont courantes : réserver les règles de frais aux moyens de paiement hors ligne, ou capturer/ajuster le montant côté passerelle. Notre support peut vous conseiller selon la passerelle utilisée.

Multiboutique et multilingue

Multiboutique — chaque règle est associée à une ou plusieurs boutiques via le champ Boutiques du formulaire. Seules les règles associées à la boutique courante sont évaluées. Une règle enregistrée sans sélection est associée à toutes les boutiques.

Multilingue — le libellé de chaque règle est traduisible dans toutes les langues actives de la boutique. Si le libellé n’est pas renseigné dans la langue du client, le module utilise le libellé global défini dans les paramètres du module.

Dépannage

Les frais ne s’affichent pas au checkout

• Vérifiez que l’option Afficher les frais dans le checkout est activée dans les paramètres du module.
• Vérifiez que la règle est active et qu’elle cible bien le moyen de paiement concerné (ou « Tous »).
• Vérifiez que le contexte du client satisfait toutes les conditions : groupe, pays de facturation, devise, montant du panier.
• Assurez-vous que le panier n’atteint pas le seuil de gratuité de la règle.
• Videz le cache PrestaShop et faites un rechargement forcé du navigateur (Ctrl+F5) pour purger l’ancien JavaScript.

Les frais s’affichent mais ne sont pas ajoutés à la commande

Le calcul au checkout et le calcul à la validation utilisent le nom technique du module de paiement. Si votre module de paiement enregistre un libellé différent du nom technique, vérifiez dans la table df_payment_fee_order qu’une ligne a bien été créée pour la commande. Si ce n’est pas le cas, créez une règle ciblant Tous les moyens de paiement pour valider le fonctionnement, puis contactez le support avec le nom du module de paiement utilisé.

Une règle ne s’applique jamais alors qu’elle semble correcte

Une règle plus prioritaire (valeur de priorité plus basse) correspond probablement en premier. Rappelez-vous que seule la première règle correspondante est appliquée. Augmentez la priorité des règles génériques ou affinez les conditions des règles concurrentes.

Le montant de TVA semble incorrect

Vérifiez la cohérence entre le réglage Montants saisis TTC et les valeurs que vous avez renseignées. Un montant saisi TTC alors que le réglage indique HT (ou l’inverse) décale la ventilation. Vérifiez également que la règle de taxe sélectionnée s’applique bien au pays de facturation du client.

Le checkout est lent ou se fige

Assurez-vous d’utiliser la version 1.0.0 ou supérieure du module, videz le cache PrestaShop et forcez le rechargement du navigateur (Ctrl+F5) pour éliminer une version JavaScript mise en cache.

Désinstallation

Désinstallez le module depuis le Gestionnaire de modules. La désinstallation supprime l’onglet d’administration, les variables de configuration et toutes les tables du module, y compris l’historique des frais appliqués aux commandes. Les totaux déjà enregistrés sur les commandes existantes ne sont pas modifiés.