Invoicing & Tax Architecture

The Payment Gateway offers an enterprise-ready invoicing system capable of issuing legally compliant invoices, generating credit notes, and executing complex, multidimensional tax calculations globally.

The Invoicing Lifecycle

Invoices enforce a strict immutability rule designed for accounting compliance. They transition through specific statuses:

1. draft: The invoice is an editable placeholder. It can be fully modified, populated via the InvoiceCorrectionService, or deleted entirely without an audit trail.
2. issued: The invoice becomes a finalized, legal entity. The legal InvoiceNumber is permanently assigned. From this point forward, the core contents cannot be mutated.
3. Void / reversal workflow: If an issued invoice must be negated, the platform performs a formal void / reversal workflow rather than mutating the invoice in place. The original invoice remains part of the legal record.
4. Payment State (Computed): Financial states such as open, partially_settled, settled, credited, overpaid, or refund-derived states are computed from settlement totals instead of being persisted as a mutable invoice status.

Invoice Corrections

Once an invoice reaches the issued state, standard mutations are blocked. However, minor corrections (e.g., typographical errors in addresses or missing metadata) can be requested via the Invoice Correction Workflow.

These corrections require a formal Reason String, User ID, and timestamp, permanently appending an Audit Trail to the metadata of the invoice. Crucially, corrections cannot alter line items or financial amounts; altering amounts requires the issuance of a Credit Note.

Gapless Sequential Numbering

Unlike the legacy transaction.externalReference, which holds the merchant-provided identifier, legal invoices require gapless, sequentially incrementing numbers.

The system utilizes an isolated invoice_sequences MongoDB collection to securely $inc and format document numbers synchronously. Organizations configure per-document layouts that define prefixes, optional middle text and suffixes, start numbers, digit width, calendar-vs-fiscal year behavior, visible period detail, and reset policy.

Supported layouts include:

• INV-2026-00001
• INV-2026-03-00001
• INV-2026-03-27-00001
• INV-20260327-00001
• INV2027AR00001

The backend calculates the visible calendar or fiscal period from the actual issue date. Sites inherit the organization-wide numbering layout and sequence policy. They may override prefixes, but they do not create independent per-site sequences or their own fiscal/calendar rules.

The Advanced Tax Engine

The tax capability is far beyond standard flat rates, supporting complex B2B and B2C cross-border scenarios including reverse charge mechanisms and small-business exemptions (e.g., German Kleinunternehmerregelung).

Supported Global Tax Schemes

• EU VAT OSS (One-Stop-Shop): Manages B2C cross-border sales of digital services within the European Union.
• EU VAT IOSS (Import One-Stop-Shop): Handles low-value goods imported into the EU constraint bounds.
• GB (UK) VAT: Full calculation for standard and zero-rated services depending on EORI classifications.
• US Sales Tax: Destination-based calculation for states where nexus criteria is established.
• CA GST/HST/PST: Dual calculation capable of applying distinct provincial (e.g., Québec QST) and national (GST) layers depending on the shipping state.

VAT Rate Versioning

To survive standard government tax code alterations, VAT rules are intrinsically version-controlled.

When a tax rate is updated, it is never changed in place. Instead, a new TaxRate record is created featuring an EffectiveFrom UTC timestamp. When generating a transaction or invoice, the tax engine resolves the applicable rate against the relevant tax-point timestamp and locks the exact decimal calculation onto the resulting record to ensure auditability and immutability.

Manual Draft Invoices And Tax Preview

Manual draft invoices, recurring-generated invoices, and transaction tax calculations intentionally share the same backend tax rules.

• If a draft invoice line omits taxRate, the backend auto-calculates the rate from seller configuration, buyer billing country, client tax-country fallback, item type, and the effective tax rate at the invoice tax point.
• If a draft invoice line includes taxRate, that line is treated as an explicit manual override.
• The Admin API exposes POST /api/v1/invoices/preview-tax so dashboard flows and API key integrations can resolve the canonical tax result before creating or updating a draft invoice.

This keeps the operator-facing invoice editor consistent with the transaction tax engine instead of relying on a frontend-only rate guess.

Checkout VAT Validation Resolution

Checkout VAT ID validation is intentionally split into two layers:

• Checkout settings decide the buyer-facing validation preference for a Site or Organization: none, format, or vies.
• Tax settings decide whether the merchant is actually allowed to use VIES-backed VAT treatment, via the organization tax capability flags.

At runtime, the Main Backend resolves an effective checkout VAT validation mode before the checkout page is rendered:

• none stays none
• format stays format
• vies stays vies only when the organization tax settings have VIES validation enabled
• vies is downgraded to format when tax VIES capability is disabled

This prevents a hosted checkout from showing successful live VIES validation to a buyer when the backend tax engine would not honor that validation for tax treatment.

In practice, this means:

• merchants configure the preferred checkout UX in Settings → Checkout
• merchants configure reverse-charge and VIES tax capability in Settings → Tax
• the hosted checkout always consumes the resolved runtime mode exposed by the Main Backend session response

EU VAT OSS: 10-Year Evidence Retention

Operating under the Union OSS scheme mandates that merchants collect and preserve proof of the buyer's establishment.

When the transaction is categorized as an EU B2C cross-border supply of a digital_service, the engine automatically intercepts the API request and mandates two non-contradictory pieces of location evidence (e.g., comparing the Billing Address Country against the physical IP Address CountryCode). If the evidence matches, it is written immutably to the TaxEvidence array inside the invoice and retained automatically for 10 years, fulfilling the compliance burden.

Canonical tax records, reports, and recalculation

For every material tax event, the Admin Backend also persists canonical tax records (stored in MongoDB, e.g. collection tax_records). These rows are the audit trail behind Tax by country, Revenue by country, and VAT OSS screens: they support drill-down from aggregates to recognized net/tax/gross amounts, buyer/tax country, recognition mode (accrual vs cash), and links back to transactions or invoices.

Report APIs accept an IANA timezone for period boundaries and filenames, and a source filter where relevant (transactions, invoices, or both). VAT OSS endpoints are keyed by calendar year and quarter. File exports are implemented as GET download endpoints (CSV, OSS XML, or Elster CSV for Germany), not JSON POST bodies.

When governments publish new rates or you change rules retroactively, operators can recalculate tax on existing transactions: a single-transaction endpoint and a bulk job with status polling regenerate tax decisions and downstream records according to current configuration. Endpoint tables live under Tax Management, Tax records, and Transactions on the Admin API reference page.