Payment Fees (dfpaymentfees) — Complete Guide

Overview

DataFirefly Payment Fees lets you apply extra fees to each payment method in your PrestaShop 8 or 9 store. The goal is twofold: pass on the real cost of a payment type (card commissions, cash-on-delivery handling, processing cheques or bank wires) and steer your customers toward the payment methods that are most advantageous for your store.

The module is built around a rules engine: each rule combines a fixed amount and/or a percentage, a calculation base, caps, a free threshold, and a set of conditions (customer group, country, currency, cart total). Fees are shown to the customer during checkout, then added automatically to the order on validation.

Installation

1. In your PrestaShop back office, go to Modules → Module Manager → Upload a module.
2. Select the dfpaymentfees.zip file downloaded from your DataFirefly account.
3. Click Install, then Configure.
4. Clear the PrestaShop cache (Advanced Parameters → Performance → Clear cache).
5. From the configuration page, click Manage fee rules to create your first rule.

General settings

The module configuration page (Modules → Module Manager → Payment Fees → Configure) contains two global settings:

• Show fees at checkout — displays the fee amount next to each payment method during checkout. Disable this if you prefer to apply fees only on validation, without announcing them in the payment method list.
• Fee label — the default label shown to the customer and on the order (for example “Payment fee”). This field is multilingual and can be overridden per rule.

Creating a fee rule

From Manage fee rules, click Add a fee rule. The form is organised into four blocks: identification, amount, caps and conditions.

Identification

• Active — enables or disables the rule without deleting it.
• Label (customer) — the text shown to the customer at checkout and on the order. Multilingual and required.
• Payment method — the target module (for example ps_wirepayment, ps_checkpayment, your card payment module…), or All payment methods for a generic rule.
• Priority — an integer. A lower value is evaluated first. See “Rule evaluation order” below.

Fee amount

• Fixed fee — a fixed amount added (for example 1.50).
• Percentage fee — a percentage applied to the calculation base (for example 2.5 for 2.5%).
• Include shipping in the % base — if enabled, the percentage applies to products and shipping; otherwise to products only.
• Tax-included calculation base — choose whether the percentage is computed on the tax-included or tax-excluded total.

Both amounts can be combined. The formula applied is:

fee = fixed_fee + (base × percentage_fee / 100)

Caps and free threshold

• Minimum fee — if the calculation returns a lower amount, this minimum is applied. 0 = no minimum.
• Maximum fee — caps the fee amount. 0 = no maximum.
• Free threshold — if the tax-included cart total reaches this amount, no fee is applied. 0 = disabled.

Application conditions

Four families of conditions let you target precisely when the rule applies. An empty list means “no restriction” on that criterion.

• Customer groups — the rule only applies if the customer belongs to one of the selected groups. Typically: apply fees to consumers and exempt business customers.
• Countries — based on the billing address country of the cart.
• Currencies — the rule only applies to the selected currencies.
• Minimum / maximum cart total — the rule only applies if the tax-included cart total falls within this range. 0 disables the corresponding bound.

In multistore, an additional Stores field lets you associate the rule with one or more stores. Leaving it empty associates the rule with all stores.

Rule evaluation order

For a given payment method, the module retrieves all active rules targeting that module (or “All”), sorted by ascending priority then by identifier. It evaluates each rule’s conditions in that order and applies the first rule whose conditions are all satisfied. Subsequent rules are ignored.

Special case of the free threshold: if a rule matches but the cart reaches its free threshold, no fee is applied — and the module does not evaluate subsequent rules. Waiving is therefore a final decision, not a simple “move on to the next rule”.

VAT handling

Two settings determine the tax treatment of fees:

• Amounts entered tax-included — indicate whether the amounts you entered (fixed fee, caps) already include VAT.
• Tax rule — the PrestaShop tax rule applied to the fee. Select No tax for fees without VAT.

The module computes the applicable rate from the tax rule and the customer’s billing address, then derives the breakdown:

• If amounts are entered tax-included: excl = incl / (1 + rate).
• If amounts are entered tax-excluded: incl = excl × (1 + rate).

Both values, along with the applied rate, are stored on the order for your accounting.

Calculation example

Rule: fixed fee 1.00 + 2% of the cart, tax-included base products + shipping, max cap 5.00, amounts entered tax-included, VAT 20%.

• Cart: 120.00 incl. tax of products + 5.00 incl. tax of shipping = base 125.00.
• Gross fee: 1.00 + (125.00 × 2 / 100) = 3.50 incl. tax.
• Below the 5.00 cap: kept as is.
• Breakdown: excl. tax = 3.50 / 1.20 = 2.92, VAT = 0.58.

Customer-facing display

When the Show fees at checkout option is enabled, the module computes the fee for each available payment method and passes it to the front office. On the /order page:

• The fee amount is appended next to the label of each affected payment method.
• A reminder appears below the payment method list for the currently selected option, and updates in real time when the customer switches payment method.

This display is purely informative: the amount actually charged is recalculated server-side on order validation.

Application to the order

On order validation (actionValidateOrder hook), the module recalculates the fee for the payment method actually used, then:

1. Updates the order totals (total_paid, total_paid_tax_incl, total_paid_tax_excl, and total_paid_real where applicable).
2. Updates the invoice totals if an invoice already exists.
3. Updates the recorded payment amount, to stay consistent with the amount collected.
4. Stores the fee line (label, tax-excl, tax-incl, rate) in the df_payment_fee_order table.

The fee line is then displayed on the order confirmation page, in the customer’s order detail, on the back-office order page, and appended to the confirmation email.

A safeguard prevents double processing: if an order already has a fee line, the module does nothing.

Payment gateway compatibility

• Offline payments (bank wire, cheque, cash on delivery, in-store payment): the behaviour is complete and unreserved. The customer sees the fee, the order and invoice include it, and you collect the displayed total.
• Redirect or embedded gateways (PayPal, Stripe, bank solutions): the amount sent to the gateway is the one computed by the payment module from the cart. Depending on your gateway and its configuration, this amount may not include the fee. Verify the behaviour in a test environment before going live.

For the latter, two approaches are common: restrict fee rules to offline payment methods, or capture/adjust the amount on the gateway side. Our support team can advise depending on the gateway you use.

Multistore and multilingual

Multistore — each rule is associated with one or more stores via the Stores field in the form. Only rules associated with the current store are evaluated. A rule saved without a selection is associated with all stores.

Multilingual — each rule’s label is translatable into all active store languages. If the label is not filled in for the customer’s language, the module falls back to the global label defined in the module settings.

Troubleshooting

Fees are not shown at checkout

• Check that the Show fees at checkout option is enabled in the module settings.
• Check that the rule is active and that it targets the relevant payment method (or “All”).
• Check that the customer’s context satisfies all conditions: group, billing country, currency, cart total.
• Make sure the cart does not reach the rule’s free threshold.
• Clear the PrestaShop cache and hard-reload the browser (Ctrl+F5) to purge the old JavaScript.

Fees are displayed but not added to the order

The checkout calculation and the validation calculation both use the payment module’s technical name. If your payment module records a label different from the technical name, check the df_payment_fee_order table to confirm a row was created for the order. If not, create a rule targeting All payment methods to validate the behaviour, then contact support with the name of the payment module used.

A rule never applies even though it looks correct

A higher-priority rule (lower priority value) is probably matching first. Remember that only the first matching rule is applied. Increase the priority value of generic rules or refine the conditions of competing rules.

The VAT amount looks wrong

Check the consistency between the Amounts entered tax-included setting and the values you entered. An amount entered tax-included while the setting says tax-excluded (or the reverse) shifts the breakdown. Also check that the selected tax rule applies to the customer’s billing country.

Checkout is slow or freezes

Make sure you are using module version 1.0.0 or later, clear the PrestaShop cache and hard-reload the browser (Ctrl+F5) to eliminate a cached JavaScript version.

Uninstalling

Uninstall the module from the Module Manager. Uninstalling removes the admin tab, the configuration variables and all module tables, including the history of fees applied to orders. Totals already recorded on existing orders are not modified.