> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Surcharges
> Add a card or bank-transfer fee on top of the amount a customer pays, and see how it is disclosed, charged, refunded, and reconciled
A surcharge is a fee added to the amount a customer pays, charged with the payment when they settle by card or bank transfer. It is not a line item, not tax, and not part of what the invoice says is owed: the invoice is settled in full by its own amount, and the surcharge rides alongside it on the [payment](/docs/invoices/payments). Use surcharges when you want to recover payment-processing costs from the payer rather than absorb them.
Surcharges are enabled per organization. Contact Alguna to turn them on for yours.
Surcharging is regulated in many countries and by the card networks, and the rules differ by jurisdiction, card brand, and sometimes by the customer's own contract. Deciding whether you may surcharge, at what rate, and with what disclosure is your responsibility as the seller of record.
***
## How a surcharge is decided
Three things have to line up before a payment is surcharged.
Rules are configured per legal entity and target a payment method, optionally narrowed by the customer's billing country and the payment currency.
Each customer carries a surcharge setting. Automatic payments follow the subscription's setting instead, so a subscription can be exempted without exempting the customer.
Only card and bank-transfer payments are surchargeable. Offline and manually recorded payments never are.
If any of the three does not hold, the customer pays the settlement amount and nothing else. Nothing fails and nothing is flagged — the payment is simply taken without a surcharge.
***
## Rules
Configure rules in the dashboard under **Settings → Workflows → Payments → Surcharges**. There is no public API for surcharge configuration; it is a dashboard-only capability.
Rules belong to a legal entity. If you sell through more than one, each entity has its own set, and a payment is only ever matched against the rules of the entity that issued the invoice.
| Field | Required | What it does |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| Label | Yes | Names the surcharge wherever it is shown to the payer and on your records, for example "Card surcharge" |
| Payment method | Yes | `payment_card` or `bank_transfer`. A rule matches one method only |
| Billing country | No | Include and exclude lists of countries, matched against the customer's billing country |
| Currency | No | Include and exclude lists of currencies, matched against the payment currency |
| Fee type | Yes | `percentage` or `flat` |
| Rate or amount | Yes | The percentage rate, or the flat amount in the payment currency |
| Enabled | No | A rule only participates in matching while it is enabled. Defaults to off |
### Filters
Leaving a dimension unfiltered means it matches anything. When you do filter, you can use an include list, an exclude list, or both:
* With an include list, the value must be in it
* With an exclude list, the value must not be in it
* The same value cannot appear in both lists of one filter
* Each list holds at most 250 values
A rule that filters on billing country never matches a customer whose billing country is unknown — Alguna cannot prove an unknown value is included or not excluded, so it declines rather than guesses. A rule with no country filter still matches that customer.
### One rule per payment
Exactly one rule may match a given payment. Alguna enforces this when you enable a rule: if it would overlap an active rule for the same payment method, with overlapping country *and* currency filters, saving is rejected and the conflicting rule is named. Overlapping in only one dimension is fine, because the other dimension keeps the two rules apart.
So these two can both be active:
| Label | Method | Billing country | Currency | Fee |
| ----------------- | -------------- | ------------------------ | -------- | ---- |
| US card surcharge | `payment_card` | Include `US` | Any | 2.9% |
| EU card surcharge | `payment_card` | Include `DE`, `FR`, `NL` | Any | 1.5% |
But adding a third card rule with no country filter would be rejected, because it overlaps both.
***
## Who gets surcharged
Every customer has a surcharge setting that governs manual payments — hosted checkout and payments you collect from the dashboard. New customers inherit the organization default, set by **Default new customers to surcharges enabled** on the surcharges settings page. You can change it on any customer at any time, and it takes effect from the next payment.
Automatic payments — autopay at invoice issuance and autopay retries — follow the subscription's own setting, on the subscription's **Invoicing settings** tab. A new subscription inherits the customer's setting at creation, after which the two are independent. If an automatic payment cannot be tied back to a subscription, it is not surcharged.
***
## Calculation
The base amount is what the payment settles: the invoice's payable amount, or, when one payment covers several invoices, the amount attributed to each invoice. Tax is already inside that figure, so a percentage surcharge is calculated on the tax-inclusive amount.
| Fee type | Surcharge |
| ------------ | -------------------------------------------------------------- |
| `percentage` | base amount × rate ÷ 100, rounded to the currency's minor unit |
| `flat` | the configured amount, rounded to the currency's minor unit |
A surcharge that rounds to zero is not applied, and a base amount of zero or less is never surcharged.
### One payment, several invoices
When a single payment settles several invoices, a percentage rule is applied to each invoice's share, because the fee scales with the amount. A flat rule is charged once for the whole payment, not once per invoice — the fee is fixed by definition, so charging it repeatedly would not match what the payer was quoted.
***
## What the payer sees
Wherever a surchargeable method can be chosen, the amount is broken out before the payer commits:
| Row | Amount |
| --------------------- | -------- |
| Settlement amount | 1,000.00 |
| Card surcharge (2.9%) | 29.00 |
| Total charged | 1,029.00 |
This appears in [hosted checkout](/docs/hosted/checkout), on the hosted invoice payment page, and in the dashboard's collect-payment dialog. Switching payment method recalculates it, and the payment cannot be submitted while a surchargeable estimate is still being calculated or has failed — the payer is never asked to approve an amount Alguna is unsure about.
The quoted figure is a display estimate. The charged amount is always recomputed server side at the moment of payment, from the same rules and the same settings, so what is charged matches what was shown.
Receipts show the surcharge as a separate amount alongside the invoice total.
***
## What a surcharge does not change
A surcharge is money collected on top of the invoice, so it stays outside every figure that measures the invoice.
| Figure | Includes the surcharge? |
| -------------------------------------- | ----------------------- |
| Invoice total and amount due | No |
| Amount paid against the invoice | No |
| Credit note total | No |
| Amount refunded on the payment | No |
| Amount charged by the payment provider | Yes |
An invoice for 1,000.00 paid with a 29.00 surcharge is fully paid at 1,000.00. The provider charged 1,029.00.
***
## Records
Each applied surcharge is stored against the payment, the invoice it was calculated for, the customer, the subscription where there is one, and the legal entity. Alongside the amount, Alguna keeps a snapshot taken at the moment of payment: the rule's label, filters, fee type, and rate or amount, the payment method used, and the figures the calculation ran on.
The snapshot is immutable. Editing or deleting a rule later changes what future payments are charged and never rewrites what an earlier payer was charged.
***
## Refunds
When you [refund](/docs/invoices/refunds) a payment that carried a surcharge, the surcharge is reversed with it. Alguna always derives that reversal — it is never an amount you supply, and it cannot be edited or overridden.
The refund amount you request is the invoice amount. The provider refund is that amount plus the surcharge portion:
* **Full refund** — the entire remaining surcharge is returned, so rounding can never strand a few cents
* **Partial refund** — the surcharge is returned in proportion to the base amount being refunded, capped at what remains unreversed
Refunds still pending count against that cap, so two partial refunds issued close together cannot together return more surcharge than was collected.
Refunding through a [credit note](/docs/invoices/credit-notes) works the same way. The credit note documents the invoice correction and its total excludes the surcharge; the surcharge reversal rides on the provider refund and is shown next to the credit note as a separate, non-editable amount.
***
## Accounting
Where an accounting integration is connected, the surcharge is synced separately from the invoice payment, into a dedicated ledger account you nominate on the integration. This keeps surcharge income out of accounts receivable, where it would otherwise look like the customer overpaid.
A payment whose invoices span more than one legal entity cannot have its surcharge synced, because there is no single entity whose books it belongs in. Set the destination ledger account before enabling surcharges, or the surcharge sync fails while the payment itself still syncs.
***
## FAQ
No. Rules are read at the moment of payment, and each applied surcharge keeps its own snapshot. Editing, disabling, or deleting a rule changes future payments only.
No. Only card and bank-transfer payments taken through a payment provider can be surcharged. Payments you record manually are never surcharged.
Rules that filter on billing country will not match them. Rules with no country filter still apply. If you want every customer covered, leave the country dimension unfiltered.
No. At most one rule can match, and Alguna blocks you from enabling rules that could both match the same payment.
Automatic payments read the subscription's setting, not the customer's. The two start out the same and drift apart if either is changed afterward. Check the subscription's invoicing settings.
Alguna does not calculate tax on the surcharge. It is collected on top of the invoice, and the invoice's tax is computed on the invoice amount alone.
***
## Related
* [Payments](/docs/invoices/payments) — how money received is recorded and attributed
* [Refunds](/docs/invoices/refunds) — returning money against a payment
* [Credit notes](/docs/invoices/credit-notes) — correcting an invoice
* [Hosted checkout](/docs/hosted/checkout) — where a payer chooses a method and sees the breakdown