RideKit
Buy the source
Docs/Reference/Government E-Invoicing — Live Wiring & Credentials

Government E-Invoicing — Live Wiring & Credentials

The platform ships a tax-provider abstraction with one plugin per country tax regime, selected automatically by the market's tax.engine (india_gst · zatca · cfdi · nfse · none). Every plugin issues a deterministic local invoice by default — a valid GST/VAT-style document with computed tax split, a locally-derived reference (IRN hash / UUID stand-in) and a QR field set — so invoicing works out-of-the-box with zero external dependencies and never blocks a completed ride.

When a buyer supplies real authority/GSP credentials (encrypted at rest via the provider-credential store, set on the admin Providers page), the plugin switches to live registration with the tax authority and uses the real returned identifiers. Any missing credential or any live-call failure falls back to the local invoice — the ride is always invoiced.

This is a graceful, credential-gated upgrade: no credentials → mock (dev/B2C); credentials → live filing.

How to enable live filing

  1. Obtain sandbox/production credentials from the relevant authority or an accredited intermediary (GSP / PAC / municipality) — see per-country below.
  2. In the admin panel → Providers → add the credential keys for the matching provider (they are AES-256-GCM encrypted at rest; only masked values are ever returned to the UI).
  3. No restart needed — the plugin resolves credentials per invoice.

Credentials may also be supplied via the process.env fallbacks listed below (useful for a single-tenant deployment), but the encrypted store is preferred.

Per-country credential requirements

🇮🇳 India GST (india_gst) — IRP via a GSP

Passenger transport is SAC 9964. Intra-state → CGST+SGST; inter-state → IGST. Live filing registers the invoice with the Invoice Registration Portal (IRP) through a GSP (e.g. Cleartax, Masters India, or the NIC sandbox).

Provider key Credential Env fallback
india_gst gspBaseUrl GSP_BASE_URL
india_gst clientId GSP_CLIENT_ID
india_gst clientSecret GSP_CLIENT_SECRET
india_gst username GSP_USERNAME
india_gst password GSP_PASSWORD

Gate: gspBaseUrl and clientId present → live. Returns the authority's real IRN, signed QR code, and AckNo/AckDt. Also set the seller GSTIN as the market's tax.sellerTaxId.

🇸🇦 Saudi Arabia ZATCA (zatca) — Fatoora reporting/clearance

15% VAT. Live filing reports/clears the signed invoice with ZATCA Fatoora.

Provider key Credential Env fallback
zatca apiBaseUrl ZATCA_API_BASE_URL
zatca binarySecurityToken ZATCA_BST
zatca secret ZATCA_SECRET

Gate: apiBaseUrl and binarySecurityToken present → live. Requires the device onboarding (CSID) done with ZATCA beforehand; set the seller VAT number as tax.sellerTaxId.

🇲🇽 Mexico CFDI (cfdi) — timbrado via a PAC

16% IVA. Live filing stamps (timbra) the CFDI through an authorized PAC.

Provider key Credential Env fallback
cfdi pacBaseUrl CFDI_PAC_BASE_URL
cfdi pacUser CFDI_PAC_USER
cfdi pacPassword CFDI_PAC_PASSWORD

Gate: pacBaseUrl and pacUser present → live. Returns the UUID (folio fiscal) and stamped-XML reference. Set the seller RFC as tax.sellerTaxId; the CSD certificate is held by the PAC.

🇧🇷 Brazil NFS-e (nfse) — municipal service invoice

ISS varies by municipality (5% placeholder). Live filing submits the NFS-e to the municipality's web service (each city differs).

Provider key Credential Env fallback
nfse municipalityBaseUrl NFSE_BASE_URL
nfse cnpj NFSE_CNPJ
nfse municipalToken NFSE_MUNICIPAL_TOKEN

Gate: municipalityBaseUrl and cnpj present → live. Returns the NFS-e number + verification code. Set the seller CNPJ as tax.sellerTaxId.

Notes

  • none engine (US and most Tier-4/5 markets): no government e-invoicing; a plain receipt is produced. VAT/sales tax, where applicable, is still computed and shown per the market tax.rateBps.
  • The QR / IRN in mock mode is a deterministic stand-in, not authority-signed — fine for development, B2C under-threshold flows, and demos; not a legal substitute for a cleared invoice in a regime that mandates one.
  • Failures are logged at error level (never silent) and the local invoice is used, so an operator sees a filing problem in logs while the customer still gets an invoice.
source: docs/E-INVOICING.md (ships identically in the product zip)