The billing engine, in detail.

Invoices, configurable reminders, multi-currency, per-country VAT, refunds, credit/wallet, proration. Payment gateways are visual plugins. PCI-scope-zero by architecture.

01 · Lifecycle

Invoices have explicit states. Every transition is logged.

Eight statuses, enforced by a database CHECK constraint. Every state change writes to the activity log with the actor, the prior state, and the trigger — cron, webhook, or user action.

States

8 statuses

unpaid: Issued by the recurring scheduler or created manually. Awaiting payment. Auto-payment cron will attempt the saved method if the customer has one.
pending: Customer initiated a gateway flow (redirect, SCA challenge, async confirmation). Waiting on the webhook to settle.
paid: Gateway settlement matched against the invoice. Service marked active. Receipt emailed via the configured template.
on_hold: Operator placed the invoice on hold. Auto-suspension and reminder cron skip it. Manual unhold required.
collections: Past the suspension grace window. Service is suspended; account flagged for follow-up. Reversible on payment.
cancelled: Invoice voided before payment. Original line items frozen for the audit trail.
refunded: Settled, then reversed through the original gateway. Original invoice kept for audit.
converted: Proforma converted into a billable invoice (proforma-first workflow). Linked back to the source document.

invoice · detail

Line items are taxed, totaled, and rounded server-side. The FX rate is captured at issue time on the line snapshot.

02 · Dunning

Configurable reminders. Configurable retries. Configurable suspension.

Up to three reminder levels fire after invoice creation on day-offsets you control. Auto-payment cron retries saved methods on a flat interval and retry count. After the grace window, the lifecycle cron suspends the service.

01.D+0
Invoice issued
Created by the recurring scheduler ahead of the renewal date or manually by an operator. Customer notified via the configured email template.
02.D+R1
Reminder 1
First post-creation reminder. Days offset is configurable per tenant (default off until you set it).
03.D+R2
Reminder 2
Second reminder, fired on its own configurable day count after invoice creation. Skipped if the invoice is on hold.
04.D+R3
Reminder 3
Third reminder. Three configurable levels in total — set the day offsets in Settings → Invoice Reminders.
05.D+G
Auto-suspend
After the suspension_grace_days window past due date, lifecycle cron suspends the linked service. Configurable per tenant; license services use their own month-based cycle.
06.D+G+T
Auto-terminate
After termination_grace_days past suspension, lifecycle cron tears down the service. Configurable; default is conservative.

R1 / R2 / R3 day-offsets, retry interval, retry count, and grace windows are all configurable per tenant. There are no pre-due reminders.

03 · Currency & VAT

Multiple currencies. Per-country VAT. Honest scope.

Customers transact in their pinned currency. You report in yours. The FX rate is captured the moment the invoice is issued. VAT is a per-country rate table with a per-customer exempt flag — no live VIES, no OSS/IOSS automation. Choose your jurisdictions, set the rates, ship.

ISO 4217all
Currencies: ECBdefault
FX feed: Per country
VAT rates: Per customer
Exempt flag

settings · currencies

FluxBilling multi-currency settings — exchange rates, FX feed, and per-customer pinning

Reporting currency: Pinned per tenant. Exchange rates captured at invoice-issue time and stored on the line item snapshot.
Customer currency: Pinned per customer. Invoices issue in the pinned currency; rates refresh from the configured FX feed on the cron schedule.
FX feed: European Central Bank reference rates by default. Override to Open Exchange Rates, exchangerate.host, or a custom provider via settings.
Per-country VAT: Lookup table of VAT rates keyed by country code. Toggle individual countries on or off; admin maintains the rates from the VAT settings page.
VAT-exempt flag: Per-customer boolean on the user record. When set, invoices issue without VAT regardless of country. Set manually for verified B2B reverse-charge cases.
Credit-deposit VAT: Separately toggled. Choose whether VAT applies to wallet top-ups or only to service invoices, per local rules.

04 · Gateways

Every gateway is a visual plugin. PCI-scope-zero by architecture.

Card data flows direct from the customer to the PSP through hosted fields or a hosted payment page. The platform never sees a PAN. Each gateway is a JSON plugin definition with a flow graph — built in the no-code editor or imported from a file — and registered into the GatewayRegistry on activation.

GatewayRegistry interface

visual plugin

createPayment(req): Returns { redirect } for hosted-page flow or { clientSecret } for embedded SCA. The flow graph builds the PSP request from the canvas.
capturePayment(txId, opts): Optional. Used by gateways that separate authorization and capture. The plugin maps it to the PSP capture endpoint.
refundPayment(txId, amount, reason): Full or partial refund through the original PSP. The activity log captures the actor, amount, and reason.
chargePaymentMethod(token, req): Charges a saved payment method off-session. Used by the auto-payment cron when the customer has a saved card and auto-pay enabled.
handleWebhook(req): Verifies the gateway's HMAC signature using the configured webhook secret, then settles the matching invoice or proforma.

Activated plugins are loaded into GatewayRegistry on startup

Visual plugin builder →

settings · gateways

FluxBilling gateway settings — Stripe, Mollie, PayPal, CoinGate toggles and credentials

Stripe
Cards · SCA · saved methods
Mollie
EU local methods · iDEAL
PayPal
Wallet · subscriptions
CoinGate
BTC · ETH · stables

Plus bundled visual plugins for 2Checkout, Authorize.Net, BitPay, CCAvenue, CoinPayments, GoCardless, Paddle, Skrill, and bank transfer.

05 · Corrections

Every reversal is logged and reversible.

Refunds, account credit, prorated upgrades, and adjustments share the same data model and the same audit trail. Auditors get one log; customers get a clean invoice and a reachable receipt.

Refund: Full or partial, processed through the original gateway via refundPayment(). The gateway plugin returns the refund record; the invoice is marked refunded and the activity log captures the actor.
Account credit / wallet: Per-customer balance maintained by creditService. Auto-applied to new invoices before any gateway charge; topped up via credit_deposit invoices.
Proration: Mid-cycle plan changes calculate the unused remainder of the current term and the prorated new term. prorationService writes one line each on the next invoice.
Adjustments: Manual line-level credits or debits on draft documents. Every change requires an actor and writes to the activity log.
Recurring vs one-time: Same invoice schema, separate billing schedules. One-time charges (setup fees, hardware, overage) and recurring renewals share line items and totals.
Proforma → invoice: Proforma-first workflow: issue a proforma, customer pays, system converts it to a billable invoice with a linked back-reference. Required in some jurisdictions for fiscal validity.

Back to all features Next: Provisioning →Payment gateway plugins

Get started

Try it on your own data. Refund inside 14 days if it’s not the fit.

Pick a tier and provision a tenant in under two minutes — isolated K3s namespace, your own database, the full product. If FluxBilling isn’t the right fit inside 14 days, open a ticket and we’ll refund the subscription. No sales call, no qualification gate.

Pick a tier Talk to sales

14-day refund

Standard policy

01.
Pick a tier
Lite from €4.95/mo. Upgrade later, no migration.
< 1 min
02.
Provision the tenant
Isolated K3s namespace + your own PostgreSQL database. Full product, your data.
< 2 min
03.
Refund inside 14 days
Not the fit? Open a ticket within 14 days and we refund the subscription. No questions, no qualification gate.
d0 — d14

14-day refund · cancel any time

Start →