UBL 2.1 XML, or PDF/A-3 with the XML embedded
Every document carries a UUID, a hash, and a cryptographic stamp establishing authenticity of origin and integrity of content. The rendered PDF a human reads is a by-product. The XML is the invoice.
W-Enterprises/Saudi Arabia/ZATCA e-invoicing integration
Saudi Arabia / Compliance engineering
ZATCA Phase 2 integration, done by the person who writes the code.
Wave 25 brings every taxpayer above SAR 187,500 in revenue into the integration phase, with a deadline of 1 February 2027. This page sets out exactly what the Fatoora platform requires, where integrations fail, and how an engagement runs.
SAR 187,500
Wave 25 revenue threshold
1 Feb 2027
Wave 25 integration deadline
24 hours
Reporting window, simplified invoices
6 years
Minimum record retention
The deadline, stated plainly
ZATCA rolls the integration phase out in waves, each one reaching a lower revenue threshold than the last. Wave 25 covers taxpayers whose VAT-subject revenue exceeded SAR 187,500 in any of 2022, 2023, 2024 or 2025, and requires integration with the Fatoora platform by 1 February 2027.
That threshold is the same figure as the voluntary VAT registration threshold in Saudi Arabia, which makes Wave 25 the bottom of the ladder. Below it a business generally cannot be VAT registered at all, so there is no obvious wave underneath. Anyone still unintegrated when Wave 25 closes is not waiting for a later wave. They are late.
Check your own notification
ZATCA notifies targeted taxpayers at least six months before their deadline. Treat the letter or portal notice you received as authoritative for your own wave and date, and treat this page as orientation. If you have not received a notification and your revenue crossed SAR 187,500 in any of the four reference years, assume you are in scope and confirm with ZATCA.
What Phase 2 actually requires
Phase 1 asked for a structured electronic invoice. Phase 2 asks for a cryptographically bound, sequence-verified document exchanged with a government API in real time. The gap between the two is where most projects underestimate the work.
01 / Format
02 / Onboarding
CSID, issued per device
The taxpayer generates a one-time password on the Fatoora portal, the invoicing unit submits a certificate signing request, and ZATCA issues a Compliance CSID and then a Production CSID after the unit passes compliance checks. Six test documents where a unit issues both standard and simplified invoices.
03 / Exchange
Clearance before issue, or reporting within 24 hours
Standard invoices clear through the Clearance API before they reach the buyer and come back stamped by ZATCA. Simplified invoices are stamped by the seller, given to the customer, and reported within 24 hours.
04 / Integrity
Hash chain and a counter that cannot reset
Each document's previous document hash must match the last document the unit generated, including rejected ones, and the invoice counter value cannot be reused or reset. This is the requirement that quietly breaks retries, failovers and database restores.
05 / Signing
ECDSA over SHA-256, XAdES in UBLExtensions
The stamping key cannot be exported from the solution. Neither can the clock be adjustable at issuance. Both are explicit prohibited-functionality items, not implementation preferences.
06 / QR
Base64 TLV, nine fields, exact order
Seller name, VAT number, timestamp, invoice total including VAT, VAT total, XML hash, ECDSA signature, public key, and ZATCA's signature of that public key. Field order and tag lengths are unforgiving, and Arabic seller names are where encoding bugs surface.
Where integrations actually fail
These are the recurring failures, in rough order of how often they turn up:
- A broken hash chain after a rejection. The chain includes documents ZATCA rejected. Systems that only chain successful documents drift out of sequence and every subsequent submission fails.
- A reset invoice counter. Redeploying a container, restoring a database, or running two instances against one CSID all produce duplicate or non-monotonic counter values.
- Malformed CSR fields at onboarding. The certificate signing request has field conventions that are not obvious from generic OpenSSL documentation, and the failure message is unhelpful.
- TLV QR encoding. Wrong tag order, wrong length prefixes, or UTF-8 handling that mangles the Arabic seller name.
- Arabic present in the PDF but wrong in the XML. The invoice looks correct to a human and fails validation, which is the most expensive category because it is discovered late.
- Timezone and timestamp drift. The issuance timestamp is bound into the signature and the QR code. A server on the wrong clock invalidates both.
None of these are hard problems individually. They are all problems that cost a week each when met for the first time under a deadline.
What this practice does, and does not, sell
It does not sell another invoicing product. That layer is already commoditised in Saudi Arabia, with capable local products at low monthly prices and Arabic-first interfaces. Replacing one of them is rarely the right advice.
What it sells is the engineering around them:
- Integration. Connecting an existing ERP, billing system or point-of-sale to the Fatoora Clearance and Reporting APIs, including CSID onboarding and the compliance document set.
- Remediation. Diagnosing and fixing an integration that is already live and failing validation. Hash chain repair, counter reconciliation, QR and XML correction.
- Migration. Moving from a Phase 1 generator to a Phase 2 integrated solution without breaking numbering continuity.
- Bilingual document correctness. Arabic and English side by side, right to left handled properly, in both the XML payload and the rendered PDF. See the write-up on Arabic PDF rendering for how that is done.
- Subcontract capacity. For ERP partners and accounting firms carrying more integration backlog than build capacity, delivered under your name.
How an engagement runs
| Stage | What happens | Typical duration |
|---|---|---|
| Readiness review | A written assessment of the current system against the Phase 2 requirement set, with a named list of gaps and a fixed quote for the build. | 3 to 5 working days |
| Sandbox integration | CSR and Compliance CSID in the ZATCA developer sandbox, the compliance document set passing, XML and QR validated. | 1 to 2 weeks |
| Production onboarding | Production CSID, clearance and reporting live, hash chain and counter persistence hardened against restart and failover. | 1 week |
| Handover | Runbook, monitoring on submission failures, and a documented recovery procedure for a broken chain. | 2 to 3 days |
Scope is fixed in writing before the build starts and out-of-scope items are named. Change requests are quoted separately.
Common questions
What is ZATCA Wave 25 and when is the deadline?
Wave 25 covers taxpayers whose VAT-subject revenue exceeded SAR 187,500 in any of 2022, 2023, 2024 or 2025, and requires integration with the Fatoora platform by no later than 1 February 2027. ZATCA notifies targeted taxpayers at least six months ahead, so confirm your own wave and date against the notification you received.
Does a business need a ZATCA-approved solution provider?
No. ZATCA states that a taxpayer may use any company's solution provided it complies with the requirements, and that a compliant taxpayer is compliant whether or not the provider appears in the Solution Providers Directory. The directory is described by ZATCA itself as a guiding, non-binding list. Compliance is certified per deployment through the Compliance and Production CSID process, not per product.
What is the difference between the Clearance API and the Reporting API?
Standard tax invoices, typically business to business and business to government, must be cleared before the invoice reaches the buyer, and ZATCA applies its stamp and QR code. Simplified invoices, typically business to consumer, are stamped by the seller and reported within 24 hours of issue, with ZATCA validating rather than clearing.
Do e-invoices have to be stored inside Saudi Arabia?
The resolutions require retention and accessibility to ZATCA rather than naming a physical location, and cloud storage is permitted where the arrangement complies with Saudi law and National Cybersecurity Authority requirements. In practice many buyers and auditors still require in-Kingdom hosting. Hosting in a Saudi region also removes the Personal Data Protection Law cross-border transfer question, so it is usually the cheaper decision overall.
Can a non-resident supplier's own invoices be caught by this?
The e-invoicing regulation applies to VAT-registered resident taxable persons and excludes non-resident taxpayers. A foreign supplier invoicing a Saudi business under the reverse charge is not issuing a Saudi e-invoice. The obligation sits with the Saudi party.
What causes most Phase 2 integrations to fail validation?
A broken previous document hash chain after a rejected or retried document, a reused or reset invoice counter, malformed CSR fields during CSID onboarding, TLV QR fields in the wrong order or with wrong tag lengths, and Arabic content that renders correctly in the PDF but is missing or mis-encoded in the UBL XML.
Facing a wave deadline?
Send the current setup, the wave you are in, and the date on your notification. You will get a written read on scope and risk within one working day, at no cost and with no obligation.
Wave thresholds, deadlines and technical requirements on this page are drawn from ZATCA's published resolutions, technical guidelines and wave announcements, and were checked in August 2026. ZATCA is the authoritative source and its requirements change. Nothing on this page is tax or legal advice. Confirm your own obligations with ZATCA or a qualified Saudi tax adviser.