ZATCA Phase 2: What the Integration Actually Involves
Phase 2 is a cryptography project wearing an accounting hat. Here is what your system really has to do, and which parts you should not build yourself.
Valeur X Team
Technology & Industry
Phase 1 asked for a PDF with a QR code. Most companies solved it in a week. Phase 2 asks your system to hold a certificate, sign every invoice in a canonical form, keep an unbroken hash chain and talk to the authority in real time. That is a different kind of work, and it is the reason so many integrations slip.
Clearance and reporting are not the same thing
A standard invoice — B2B, to a registered buyer — must be cleared by ZATCA before you may hand it to the customer. A simplified invoice — B2C, the receipt at the counter — is reported afterwards, within twenty-four hours. Getting this backwards is the most common design error we see, and it produces a compliance failure that looks exactly like success: the invoice goes out, nobody is told.
- Onboarding: a certificate signing request and an OTP exchange with Fatoora
- Signing: canonical XML, signed byte for byte with your own certificate
- Chaining: each invoice carries the hash of the one before it
- Submission: clearance for standard invoices, reporting for simplified ones
- Archiving: the signed document, kept and retrievable
The hash chain is unforgiving
Every invoice references the previous one. Restore a database backup, run two servers that both think they are next in line, or delete a test invoice from production, and the chain breaks. Recovering from that is not a code change — it is a conversation with the authority. Design for it before go-live, not after.
A rejected invoice is not a document. It is one the authority has refused, and sending it to your customer creates an obligation you cannot support.
What not to build yourself
The signing implementation has to match the official SDK byte for byte, or the authority rejects it for reasons the error message will not explain. Unless you plan to maintain that against every specification update, this is the part to buy — through an API that takes your invoice and returns the signed XML, the QR and the PDF. Your own system keeps doing what it is good at.
Budget for a sandbox period with your real invoice shapes. Every company discovers at least one — a credit note, a multi-line discount, an exempt item, a foreign-currency sale — that behaves differently from the examples in the specification.
