DEV Community: Mousa Hammad

ZATCA Wave 25: What Developers Integrating Before 1 February 2027 Need to Know

Mousa Hammad — Fri, 07 Aug 2026 13:23:27 +0000

On 24 July 2026, Saudi Arabia's ZATCA announced the selection criteria for Wave 25 of Phase 2 e-invoicing integration: taxpayers whose taxable turnover exceeded SAR 187,500 in 2022, 2023 or 2024 must integrate their systems with the Fatoora platform no later than 1 February 2027.

That is the lowest threshold in the entire rollout. Waves 1 through 24 walked the number down from SAR 3 billion to SAR 375,000; Wave 25 halves it again. In practice it means Phase 2 now reaches almost every VAT-registered business in the Kingdom - and the developers building for them are meeting the integration for the first time.

If that is you, here is what actually matters, from having shipped one.

Phase 2 is not "add a QR code"

Phase 1 was a printed TLV QR with five fields. Phase 2 is a different animal:

Onboarding - generate a keypair, build a CSR with ZATCA-specific extensions, exchange it for a compliance certificate (CCSID), pass compliance checks, then exchange those for a production certificate (PCSID).
Signing - canonical UBL 2.1 XML, an invoice hash over a precisely-scoped subset of the document, an ECDSA signature on the secp256k1 curve, and a XAdES signature block.
QR - now nine TLV tags, including the invoice hash, your signature, your public key, and the CA's signature over your certificate.
Submission - simplified (B2C) invoices are reported after issue; standard (B2B) invoices are cleared before the buyer gets them.
Chain - every invoice carries a strictly-increasing counter (ICV) and the previous invoice's hash (PIH), making deletions provable.

Budget accordingly. The XML is the easy part.

The part nobody warns you about

ZATCA's real contract lives in its gateway's behavior, not in its documentation. A few examples that each cost me a live rejection to find:

Each environment demands a different CSR certificate template. TSTZATCA-Code-Signing for sandbox, PREZATCA-Code-Signing for simulation, ZATCA-Code-Signing for production. Send the wrong one and the gateway replies with a bare Invalid Request - before it reads anything else in your CSR.
The device serial belongs in the surname OID (2.5.4.4), not serialNumber (2.5.4.5), because ZATCA's own OpenSSL config wrote SN= and OpenSSL maps that to surname. The semantically correct field is rejected.
secp256k1 works in Node and dies in Electron. Electron links BoringSSL, which refuses the curve (UNKNOWN_GROUP). Every test passes on your machine; the packaged desktop app throws at the first signature.
The XAdES SignedProperties block must exist in two different byte-shapes - one you hash, one you embed - and its digest is base64 of the hex string, not of the raw bytes.
Compliance-green is not reporting-green. /compliance/invoices does not verify the SignedProperties digest at all. You can pass all four compliance documents, collect your production CSID, and fail on your very first real invoice with signed-properties-hashing.

There are ten of these. I wrote them all up, free and in full: github.com/mousah20/zatca-phase2-traps

A realistic plan for the six months you have

Now to October: get onboarding working against the sandbox. Any OTP is accepted there, so there is nothing to wait for. Getting a compliance CSID issued proves your CSR is correct, which is where most of the early time is lost.

October to December: sign and submit all four document types (simplified and standard invoices, credit and debit notes). Then move to the simulation environment with a real Fatoora-portal OTP and, crucially, get an accepted reporting call - not just compliance checks.

December to February: production onboarding with your taxpayer's certificate, then run both systems in parallel briefly before switching over. Leave room for the ICV/PIH chain work: the counter must be reserved inside the same database transaction that writes the invoice, or two concurrent sales take the same number and every invoice after the duplicate is rejected.

Do not leave the integration to January. The gateway's error messages are terse, and each round trip through "reject, guess, retry" costs days.

Shortcuts

If you work in Node.js, the QR encoder alone (all nine Phase-2 tags, byte-correct for Arabic seller names) is MIT-licensed on npm: zatca-qr-tlv.

And if you would rather not spend the six months at all, I packaged the entire integration - onboarding, signing, QR, reporting and clearance - as a production-proven SDK with a live test that onboards a device against ZATCA's sandbox and gets an invoice REPORTED in about two minutes.

Not affiliated with ZATCA. Wave 25 criteria as announced on 24 July 2026; confirm your own wave and deadline through the Fatoora portal.

Why Your ZATCA Phase 2 Invoice Passes Compliance and Fails Reporting

Mousa Hammad — Fri, 07 Aug 2026 12:36:09 +0000

If you are integrating ZATCA Phase 2 (Saudi Arabia's Fatoora e-invoicing) and you have seen this:

{
  "type": "ERROR",
  "code": "signed-properties-hashing",
  "category": "CERTIFICATE_ERRORS",
  "message": "Invalid signed properties hashing, SignedProperties with id='xadesSignedProperties'"
}

...after your invoice sailed through /compliance/invoices, this post is for you. It is the single most confusing failure mode in the whole integration, and the fix is not what the error suggests.

The trap: SignedProperties exists in two byte-shapes

The XAdES SignedProperties block is referenced twice in your signed document:

ds:Reference URI="#xadesSignedProperties" carries a digest of the block.
The block itself is embedded inside ds:Object > xades:QualifyingProperties.

The natural assumption is that both refer to the same bytes. They do not.

The hashed shape carries namespace declarations and starts at column 0:

<xades:SignedProperties xmlns:xades="http://uri.etsi.org/01903/v1.3.2#" Id="xadesSignedProperties">
                                    <xades:SignedSignatureProperties>
                                        <xades:SigningTime>2026-08-07T02:14:33</xades:SigningTime>
                                        <xades:SigningCertificate>
                                            <xades:Cert>
                                                <xades:CertDigest>
                                                    <ds:DigestMethod xmlns:ds="http://www.w3.org/2000/09/xmldsig#" Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>

The embedded shape carries no namespace declarations (they are inherited from ancestors) and its root element is indented to column 32:

                                <xades:SignedProperties Id="xadesSignedProperties">
                                    <xades:SignedSignatureProperties>

Embed the hashed shape verbatim - the intuitive thing to do - and the gateway rejects with signed-properties-hashing, even though your indentation "looks right".

The second half of the trap: the digest encoding

The digest is not the raw SHA-256 bytes in base64. It is base64 of the hex string:

const crypto = require('crypto');

// hashedShape = the namespaced, column-0 variant above
const propsDigest = Buffer.from(
  crypto.createHash('sha256').update(Buffer.from(hashedShape, 'utf8')).digest('hex'),
  'utf8'
).toString('base64');

If you used .digest('base64') you produced a valid-looking digest that ZATCA will never match. The same convention applies to the certificate digest.

Why compliance checks did not catch it

This is the part that costs people days: /compliance/invoices does not verify this digest at all. Only /invoices/reporting/single (and clearance) does.

So the workflow that feels safe - pass all four compliance sample documents, obtain your production CSID, celebrate - proves nothing about this block. Your first real invoice is the first time anything checks it.

Rule of thumb: compliance-green is not reporting-green. The only proof your signing is correct is an accepted reporting call.

The fix

Generate both shapes from one function so they can never drift:

const signedPropsBlock = (withNamespaces) => {
  const xades = withNamespaces ? ' xmlns:xades="http://uri.etsi.org/01903/v1.3.2#"' : '';
  const ds    = withNamespaces ? ' xmlns:ds="http://www.w3.org/2000/09/xmldsig#"'   : '';
  const lead  = withNamespaces ? '' : ' '.repeat(32);
  return \`\${lead}<xades:SignedProperties\${xades} Id="xadesSignedProperties">
                                    <xades:SignedSignatureProperties>
                                        <xades:SigningTime>\${signingTime}</xades:SigningTime>
                                </xades:SignedProperties>\`;
};

const hashed   = signedPropsBlock(true);   // digest this one
const embedded = signedPropsBlock(false);  // put this one in the document

Two more details that bite here:

SigningTime must have no Z suffix and no milliseconds - the validator reformats it as %Y-%m-%dT%H:%M:%S.
The indentation inside the template is part of the contract. The validator rebuilds this block from a fixed template and compares digests, so "prettifying" your XML output breaks it.

And while you are here: the hash scope

A related failure that produces a different opaque rejection - the invoice hash itself is SHA-256 over the canonical XML without the XML declaration (C14N drops it) and without three elements: ext:UBLExtensions, cac:Signature, and the AdditionalDocumentReference whose ID is QR.

When you insert those blocks after hashing, they must add zero new text nodes. The verifier strips element subtrees but keeps surrounding whitespace - so a single newline between the inserted QR reference and cac:Signature changes the canonical form and breaks the hash. Butt them directly together, with no whitespace between the two elements.

Nine more of these

ZATCA's real contract lives in its gateway's behavior, not its documentation. I hit ten undocumented rules like this while shipping a POS integration - each discovered through a live rejection, none caught by 256 green local tests. Things like: each environment demanding a different CSR certificate template (wrong one gives a bare Invalid Request before your CSR is even read), the device serial belonging in the surname OID because ZATCA's own OpenSSL config wrote SN=, and secp256k1 working in Node but throwing UNKNOWN_GROUP inside Electron.

I documented all ten, free and in full: github.com/mousah20/zatca-phase2-traps

If you just need the QR part, the TLV encoder (all 9 Phase-2 tags, byte-correct for Arabic seller names) is on npm as zatca-qr-tlv, MIT licensed.

And if you would rather not spend a month on this at all, I packaged the entire integration - onboarding, signing, QR, reporting and clearance - as a production-proven Node.js SDK with a live test you can run against ZATCA's sandbox in two minutes.

Not affiliated with ZATCA. Behavior described as observed in August 2026.