Built for ZATCA Phase 2
The module prepares Phase-2 e-invoice artifacts from documents you have already posted: UBL 2.1 XML, the ICV counter, the PIH hash chain and the Base64 TLV QR payload. It is precise about what it produces, and equally precise about what only ZATCA can issue.
What the module produces
Four artifacts are prepared per document, from the same posted invoice that drives your ledger. Nothing is re-keyed and nothing is reconstructed from a report.
UBL 2.1 XML
Each invoice is generated as a UBL 2.1 XML document — the structured format Phase 2 is built around. The seller details, line items, totals and tax amounts come from the posted document rather than from a separate e-invoicing data entry step.
The ICV invoice counter
Every document carries an invoice counter value that increments across the sequence. The counter is what makes a missing invoice visible: numbers do not skip quietly, because the next document expects to follow the last one.
The PIH hash chain
Each invoice stores the previous invoice hash, so documents are linked rather than merely stored side by side. Chain integrity is verified on every read — not on a nightly job, and not only when you ask for a report.
The Base64 TLV QR payload, tags 1–5
The QR payload is encoded as Base64 tag-length-value covering the five data tags: seller name, VAT number, timestamp, invoice total and VAT total. Those five are produced in full, from the document itself.
What it deliberately does not do
A QR code that looks right and is not is worse than no QR code at all, because nobody finds out until an audit does. So the module stops exactly where the credential stops.
CSID issued by ZATCA during device onboarding. Until that credential is in place, documents stay flagged signed: false.
The last four tags of the QR payload are not additional formatting. They are cryptographic material derived from a real certificate that only ZATCA can issue, to a specific device, during onboarding. There is no way to produce them from data the app already holds — and any product that appears to do so is producing something that will not verify.
Meezan ERP stores that credential once you have it, and never invents it. Before it exists, documents are prepared, hashed, counted and queued, and they are marked signed: false so the state is visible in the application rather than implied by its absence. After it exists, the same documents sign.
We treat this as an integrity decision rather than a gap. Everything that can honestly be prepared in advance is prepared in advance; the one part that depends on a credential from the authority waits for that credential. It is also why nothing on this page claims a status that only ZATCA can confer — that determination is made by the authority, about your business and your device, and it is not a software vendor's to announce on their behalf.
- No signature is generated without a real
CSID. - No placeholder certificate is written into tags 6–9.
- No document is marked as signed when it is not.
- No claim of a status that only ZATCA can confer on your business and your device.
The hash chain, explained
The point of the chain is not the hash. The point is that documents can only be a valid sequence if every one of them agrees about the one before it.
An invoice is issued
It is written with an ICV — its position in the sequence — and a hash of its own contents. That hash becomes the thing the next document has to carry.
The next invoice carries the previous hash
The PIH on document two is the hash of document one. In the test suite that is asserted directly: the second PIH equals the first hash — the chain links.
The counter keeps climbing
The ICV increments alongside the chain, so each document has both a position and a parent. Two independent signals of sequence, not one.
The chain is re-verified on every read
Verification is not an occasional maintenance task. Whenever documents are read back, the links are checked, so a problem surfaces the next time somebody opens the list.
A break is visible, not silent
An invoice that has been deleted or edited after the fact no longer matches the hash the following document is holding. The sequence stops agreeing with itself, and that shows up as a break rather than disappearing into the data.
Why this matters more than it sounds
Deleting an awkward invoice is the oldest trick in retail accounting, and in most systems it leaves nothing behind. A hash chain removes that option: you can still post a correction, but you cannot quietly remove history and have the remaining documents still line up.
It fits the rest of the ledger's behaviour. Posted journal entries cannot be edited in place — a correction posts a reversal and the original stays visible and auditable. Unbalanced entries are rejected outright, as are postings to unknown accounts.
How you would actually roll this out
Four steps, in this order. The first two are yours and immediate; the third is between you and ZATCA; the fourth flips the switch.
-
Set your VAT registration details in Settings
Company name and VAT registration number are what populate the seller tags in the QR payload and the header of the UBL document. Get these right once and every subsequent document inherits them.
-
Issue invoices normally
Nothing about day-to-day work changes. Sales invoices and POS tickets post the way they always do, and the e-invoice artifacts are prepared per document as a consequence of posting — the XML, the ICV, the PIH link and the tags 1–5 QR payload.
-
Complete ZATCA device onboarding to obtain your CSID
This is the step that issues the cryptographic identity for your device. It is a process run with ZATCA against your own VAT registration, and it produces the credential that tags 6–9 depend on.
-
Load the credential, and documents sign
Once the
CSIDis stored in the app, the signature and certificate tags can be produced and documents stop being flaggedsigned: false. The invoices you issued before that point are unchanged; the chain and the counter carried on regardless.
CSID on your behalf. What it does is store the credential securely once you have it, and refuse to pretend it exists until then.
The vocabulary, briefly
Phase 2 comes with a lot of acronyms. Here is what each one means in the context of this module, kept short.
- ZATCA
The Zakat, Tax and Customs Authority — the Saudi authority responsible for the e-invoicing programme.
- Phase 2 (integration phase)
The stage of the programme that requires structured, machine-readable invoices with cryptographic elements, rather than a QR code alone.
- UBL 2.1
Universal Business Language 2.1 — the XML document standard the e-invoice is expressed in.
- ICV
Invoice counter value. An incrementing number that fixes each document's position in the sequence.
- PIH
Previous invoice hash. The hash of the preceding document, carried by the current one so the two are linked.
- TLV QR
A tag-length-value payload, Base64 encoded, printed as a QR code. Tags 1–5 hold seller name, VAT number, timestamp, invoice total and VAT total.
- CSID
The cryptographic stamp identifier issued by ZATCA during device onboarding. It is what makes the signature tags possible.
- Simplified vs standard tax invoice
A simplified invoice is the one you hand a walk-in customer at the till; a standard tax invoice is issued business to business and carries the buyer's registration details.
It is part of the ledger, not a bolt-on
ZATCA e-Invoicing sits in the Sales group of the sidebar, immediately alongside Sales Invoices, Credit Notes and Receivables. That placement is the design: e-invoicing is a property of a sale, not a separate application you reconcile against later.
The same posted document drives all three outcomes. It writes the double entry into Journal & Ledger, it carries the VAT that settles on your return, and it produces the e-invoice artifacts. There is one number, in one place, used three ways.
- No export step. Nothing is copied from the accounts into an e-invoicing tool, so the two cannot drift apart.
- Credit notes are documents too. They live in the same Sales group and follow the same posting rules as the invoices they correct.
- POS tickets included. A till sale is a posted document like any other, VAT extracted from the gross rather than added on top.
- All of it offline. Artifacts are prepared locally, with no network calls anywhere and the database as a single file on your own disk.
Planning a ZATCA rollout
Tell us how you invoice today and which devices need onboarding, and we will walk through what the module prepares, what your CSID unlocks and the order to do it in. No obligation, and no claims we cannot stand behind.