ZATCA Phase 2 E-Invoicing: A Developer's Guide to XML, Hashing, Signing and Clearance
Saudi Arabia's e-invoicing programme (FATOORA) has moved well beyond "generate a PDF with a QR code". In Phase 2, every invoicing system has to produce structured XML, sign it, chain it to the previous invoice and talk t
Saudi Arabia's e-invoicing programme (FATOORA) has moved well beyond "generate a PDF with a QR code". In Phase 2, every invoicing system has to produce structured XML, sign it, chain it to the previous invoice and talk to ZATCA's APIs in real time or within 24 hours.
I've worked on several of these integrations across POS, ERP and custom billing systems. This post is the practical overview I wish I'd had at the start: the moving parts, the order to build them in, and the bugs that cost the most time.
The big picture
Phase 2 has two flows:
- Standard tax invoices (B2B) go through clearance. You send the signed XML to ZATCA, it validates and stamps it, and only then do you share it with the buyer.
- Simplified tax invoices (B2C) go through reporting. You issue the invoice to the customer immediately, then report it to ZATCA within 24 hours.
Credit notes and debit notes follow the same flow as the invoice type they relate to.
The building blocks
1. UBL 2.1 XML
Each invoice is a UBL 2.1 XML document with ZATCA-specific fields: seller and buyer details, VAT breakdowns, invoice type codes, an Invoice Counter Value (ICV) and the Previous Invoice Hash (PIH).
Tip: build a single function that maps your internal invoice model to XML, and unit-test it against ZATCA's sample invoices before touching anything else.
2. Invoice hash and the hash chain
Each invoice is hashed (SHA-256) over a canonicalised version of the XML, with the signature-related parts excluded. That hash becomes the PIH of the next invoice from the same device or system.
This chain is why you can't "just regenerate" an invoice later. If invoices are created out of order, or a failed invoice is dropped silently, the chain breaks.
3. Cryptographic stamp
Invoices are signed with an ECDSA key pair, using the certificate issued to that device or system. The signature and related values are embedded in the XML.
4. QR code
Simplified invoices carry a TLV-encoded, Base64 QR code. Phase 2 adds fields beyond the Phase 1 basics (seller name, VAT number, timestamp, totals), including the invoice hash, the signature and the public key.
5. Onboarding and CSIDs
Each invoicing unit is onboarded roughly like this:
- Generate a key pair and a CSR containing the required fields.
- Request a compliance CSID using an OTP from the FATOORA portal.
- Pass the compliance checks by submitting sample invoices of each type you'll issue.
- Exchange it for a production CSID.
Certificates expire, so renewal needs an owner and a reminder. Otherwise invoicing stops on the day the certificate does.
Order I'd build it in
- XML generation, with tests against the official samples
- Canonicalisation and hashing
- Signing and the QR code
- A sandbox client for the compliance APIs
- Onboarding (CSR to production CSID)
- A queue for clearance and reporting, with retries
- Monitoring and alerting for rejected or stuck invoices
The bugs that cost the most time
- Canonicalisation mismatches. A single whitespace or namespace difference changes the hash. Always hash exactly what you send.
- Rounding. Line-level versus invoice-level VAT rounding has to match ZATCA's validation rules.
- Credit notes. They must reference the original invoice correctly, and they're where "it worked in testing" usually breaks.
- Offline branches. POS terminals lose internet. Queue invoices locally, keep the hash chain intact and report when you're back online.
- Concurrency. Two invoices created at the same moment on the same unit can corrupt the ICV/PIH sequence. Serialise per invoicing unit.
- Dirty master data. Missing buyer VAT numbers or addresses cause clearance rejections. Clean the customer master early.
Build vs buy
If your team knows your billing code well and has time to learn the specs, building in-house is very doable. Otherwise, reusing tested components saves a lot of time. At Vocxa we package this as ready-to-deploy ZATCA e-invoicing integration code for Saudi businesses.
If you're also choosing an ERP, POS or accounting tool that needs to support ZATCA, comparing options on a software comparison platform with verified reviews is a good way to check which vendors actually support Phase 2.
Wrapping up
Phase 2 isn't conceptually hard, but it's unforgiving about details: canonical XML, a strict hash chain, certificates that expire and APIs that reject anything slightly off. Get the foundations right, test the awkward cases (returns, offline mode, concurrency) and monitor everything.
Happy to answer questions in the comments if you're working on a FATOORA integration.
Originally published by Dev.to Security. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.