Gateway Fee for CoreInto

An add-on module for CoreInto that charges clients a fee for paying with a particular payment method. The fee is a separate line on the invoice ("Payment processing fee (Card)"), so clients see exactly what they pay for.

Installing#

1. Copy this gatewayfee folder into the modules folder of your CoreInto installation (next to app).
2. In the admin area, open Settings > Add-on Modules and press Activate next to Gateway Fee.
3. Press Configure (or open Add-ons > Gateway Fees) and set the fees.

Configuring needs the Add-on Modules settings permission.

Settings#

The configuration page lists every active payment gateway. For each one:

• Fee type: None, Percentage, Fixed amount, or Percentage plus fixed.
• Percentage: up to three decimals, such as 2.9.
• Fixed amount: one amount per currency, because invoices are in the client's currency. A currency left empty has no fixed part.
• Minimum fee / Maximum fee: optional, per currency.
• Line on the invoice: the text clients see. Empty means Payment processing fee (%s); %s is replaced with the gateway's name.
• Taxed: whether tax is charged on the fee itself.

How fees behave#

• The fee is worked out on the total of the invoice's other lines, including tax, and rounded to the cent (to whole units for a currency shown without decimals).
• It always follows the invoice's current payment method while the invoice is unpaid: it is added when an invoice is made, and replaced (or taken off) when the client picks another way to pay on the invoice page, pays with a kept card of another gateway, chooses a method when adding funds, or staff change the payment method in the invoice options or charge a kept card.
• Paid, cancelled and refunded invoices, and invoices with a payment already recorded, are never changed. Staff can edit or delete the fee line by hand.
• A payment recorded by staff through another method keeps the fee of the method chosen on the invoice; change the method first if the fee should follow. Automatic card charges by the automation task also keep the fee of the invoice's method.
• Add-funds invoices get a fee too; the credit added is still the amount the client asked for.
• A mass payment invoice (several invoices paid together) charges one fee on the whole, less the fees already on the included invoices, so nothing is charged twice (the line can be negative when the chosen method is cheaper).
• The "Pay with" list on the client's invoice shows each method's fee, such as "Card (Stripe) + 3%".
• Deactivating the module stops adding fees. Fee lines already on unpaid invoices are left as they are. The settings are kept.

For developers#

The module listens to the core events invoice.created, invoice.gateway (fired by Invoices::setGateway()) and invoice.changed (fired when a client's currency change re-prices an unpaid invoice). Fee lines have kind = 'gateway_fee' and rel_id = 0; totals are worked out with Invoices::recalc(). Another module that changes the lines of an unpaid invoice can bring the fee up to date with Addons::get($db, $settings, 'gatewayfee')?->fees()->apply($invoiceId).