Design an ISP Billing System Around Boundaries, Not Features

Feature count is a poor architecture test

A billing platform can advertise invoices, SMS, payment gateways and automatic suspension while still leaving operators unable to answer a basic question: why did this customer lose service at 10:14? The answer crosses several boundaries. A financial event affected an account balance, a policy converted that balance into entitlement, and a network action enforced the result.

Reliable automation keeps those concerns connected but distinct. Money should not be rewritten to correct a service mistake. A router session should not become the accounting ledger. A payment callback should not directly edit a customer’s expiry date without leaving a durable financial event.

Start with immutable business events

When an operator needs to repair history, deletion is tempting and dangerous. Prefer compensating events. A mistaken receipt is reversed by an authorized reversal; it is not silently removed. An incorrect invoice receives a credit or cancellation record according to local accounting rules. This preserves the chain that managers, customers and auditors need.

Calculate entitlement in one place

The decision “may this subscriber connect?” should be reproducible from stored inputs. Those inputs may include account status, paid-through date, grace window, manual holds, contract state and an approved exception. Put their precedence in one policy service or domain layer rather than distributing slightly different conditions across dashboards, cron jobs and router scripts.

Use effective timestamps for future changes. If a package migration begins next month, store the scheduled transition separately from the current package. Overwriting the active record early makes current invoices, RADIUS policy and reports disagree.

Make payment callbacks idempotent

Payment gateways retry. Networks time out. Customers refresh pages. A callback handler must expect the same provider event more than once and produce one financial result. Use the gateway’s immutable transaction identifier as an idempotency key and verify amount, currency, merchant context and cryptographic authenticity before posting a receipt.

1. Receive the event. Store a safely redacted request fingerprint and provider event ID.
2. Verify authenticity. Follow the gateway’s signature or token verification procedure.
3. Resolve the intended account. Do not trust a customer identifier simply because it appears in browser-controlled data.
4. Check idempotency. Return the previous result when the provider event was already processed.
5. Post the financial event. Commit ledger and receipt data in one database transaction.
6. Recalculate entitlement. Publish a separate service-state change only when the policy result changes.

Queue network enforcement

A financial database transaction should not wait for a router API. Commit the business event first, then enqueue a uniquely identified enforcement job. The job can retry against a router or RADIUS service without duplicating the invoice or receipt.

Record desired state and observed state. If the account should be suspended but a router is unreachable, the platform must show “suspension pending” rather than pretending the operation completed. When the device returns, reconciliation compares desired policy with actual sessions and configuration.

Use permissions that match financial risk

“Can access accounts” is too broad. Separate viewing a ledger, recording an offline payment, reversing a payment, issuing credit, changing a tax profile and exporting financial data. High-impact actions should require a reason and, where the business needs it, second approval.

• Operators may collect within assigned customers without changing historic entries.
• Support may see payment status without seeing gateway credentials or full financial exports.
• Accounts staff may post and reconcile payments but not alter network inventory.
• Managers may approve reversals above a threshold and review exception reports.
• System jobs use service identities with narrower rights than an administrator.

Measure exceptions, not only totals

Revenue and collection totals matter, but they do not reveal whether automation is trustworthy. Track payment events awaiting verification, receipts without matched settlements, enforcement jobs exceeding retry limits, active sessions for suspended accounts, and customers whose entitlement cannot be explained.

A practical acceptance test

• Submitting the same successful gateway callback twice creates one receipt.
• A receipt reversal preserves the original event and recalculates entitlement.
• A router outage does not roll back a confirmed payment.
• A scheduled package change leaves today’s service policy unchanged.
• Every manual suspension and reactivation identifies actor, reason and time.
• Reports reconcile invoice, receipt, refund and ledger totals for the same period.
• A support user cannot discover or modify payment gateway secrets.

Research basis: established double-entry and audit-trail principles, payment-provider idempotency practices, PCI DSS scoping guidance, and the separation between RADIUS policy/accounting and the financial ledger. Tax and invoice requirements must be adapted to the ISP’s jurisdiction.