ZATCA Phase 2 Integration: A Technical Guide for ERP and Billing Systems

ZATCA Phase 2 integration is the technical connection between your ERP, billing or point-of-sale system and ZATCA's FATOORA platform. Each invoicing unit is onboarded with a Cryptographic Stamp Identifier (CSID), then submits signed UBL 2.1 XML invoices through APIs: standard B2B invoices for clearance before they reach the buyer, simplified B2C invoices for reporting within 24 hours.

The Zakat, Tax and Customs Authority (ZATCA) began the integration phase on 1 January 2023 and has rolled it out in waves, notifying each group of taxpayers at least six months in advance, as set out on its roll-out phases page. On 24 July 2026, ZATCA announced the 25th wave: taxpayers whose VAT-able revenue exceeded SAR 187,500 in 2022, 2023, 2024 or 2025 must integrate by 1 February 2027. That threshold brings many mid-sized businesses, and the in-house or legacy systems they run, into scope.

This article is for the people who have to make the integration work: IT managers, ERP owners and development teams. For the wider picture of obligations, invoice types and deadlines, see our e-invoicing guide for Saudi Arabia. Here we focus on the engineering: onboarding, the clearance and reporting flows, testing and error handling.

How does the Phase 2 integration architecture work?

ZATCA's model is built around the e-invoice generation solution (EGS) unit: the device, application or service instance that issues invoices. Each EGS unit has its own cryptographic identity and its own invoice chain. A single company may have dozens of EGS units across branches, tills, e-commerce channels and ERP instances.

For every document, the EGS unit must:

• Generate the invoice, credit note or debit note as UBL 2.1 XML with ZATCA's required fields.
• Assign a UUID and an invoice counter value (ICV) that is never reused.
• Include the previous invoice hash (PIH), chaining every document to the one before it.
• Hash and sign the document with the unit's private key and certificate.
• Build the QR code and submit the XML to the correct ZATCA API.
• Store the result, including ZATCA's response, for audit.

Because the invoice sequence is per EGS unit and covers both B2B and B2C documents, the way you define units has a direct impact on concurrency, failover and how easily you can scale.

How does CSID onboarding work?

Before an EGS unit can submit live invoices, it must be onboarded. According to ZATCA's E-Invoicing Detailed Technical Guideline, the process runs as follows:

1. Generate an OTP on the FATOORA portal. A taxpayer user logs in and generates one-time passwords. Each OTP is valid for one hour, and up to 100 can be generated in one request, which helps when onboarding many units. There is no API for OTPs; they come from the portal only.
2. Create a key pair and CSR. The EGS unit generates its private key and a certificate signing request containing mandatory fields, including a common name, serial number, VAT or group VAT number, organisation unit and name, country, the invoice types the unit will issue (standard, simplified or both), location and industry.
3. Request a compliance CSID. The EGS calls the Compliance CSID API with the CSR and OTP and receives a compliance CSID.
4. Pass the compliance checks. Using the compliance CSID, the unit submits sample documents: a standard invoice, credit note and debit note for standard issuance, and the simplified equivalents for simplified issuance. If a check fails, the process restarts with a new OTP and CSR.
5. Request the production CSID. Once checks pass, ZATCA's certificate authority issues the production CSID, which authenticates the unit for the core clearance and reporting APIs.
6. Protect and renew. Store the private key securely, monitor certificate expiry and renew before it lapses. Renewal follows the same flow and revokes the previous CSID.

Two practical notes: newly VAT-registered taxpayers must wait two business days before onboarding, and CSIDs can be revoked manually through the portal or automatically, for example after VAT deregistration.

What is the difference between clearance and reporting?

Aspect	Clearance	Reporting
Documents	Standard tax invoices and their credit and debit notes (mainly B2B)	Simplified tax invoices and their notes (mainly B2C)
Timing	Before the invoice is shared with the buyer	Within 24 hours of the transaction being completed
Who stamps it	ZATCA validates, stamps and adds the QR code	The seller's EGS signs it and generates the QR code
Validity	Only valid once cleared by ZATCA	Issued immediately; reporting follows
On rejection	Fix errors and submit a new document with a new UUID, ICV, hash and timestamp	Correct and resubmit; the customer copy need not be reissued

The difference drives architecture. Clearance is synchronous and sits on the critical path of your billing process, so latency and availability matter. Reporting can run asynchronously from a queue, as long as the 24-hour window is met.

What must every Phase 2 invoice contain technically?

• UBL 2.1 XML. ZATCA's APIs accept XML; a PDF is not a substitute for the submission.
• Hash. A SHA-256 hash of the canonicalised invoice, calculated after removing the UBL extensions, QR and signature elements, encoded in Base64.
• Signature. An ECDSA signature over the hash using the unit's private key, with the certificate referenced in the signed properties.
• Chain integrity. The PIH must equal the hash of the last document the unit generated. Rejected documents still count in the chain, and ICVs and UUIDs must never be reused.
• QR code. A Base64-encoded TLV structure of up to 700 characters. Tags cover the seller name, VAT number, timestamp, totals, invoice hash, signature and public key, and for simplified documents the stamp signature from ZATCA's certificate authority.

Because the stamp and QR string are excluded from the hash, an EGS can generate the next invoice without waiting for clearance of the previous one, which matters for high-volume billing.

How should you test in the sandbox and simulation environments?

ZATCA provides two distinct test environments, and a sound plan uses both.

The developer portal and sandbox

ZATCA's e-invoicing developer portal, described in the Developer Portal Manual, offers a downloadable Java SDK for offline validation of XML invoices, notes and QR codes; a web-based validator for up to five XML files; and an integration sandbox exposing the Compliance CSID, Production CSID, compliance check, reporting and clearance APIs. Sandbox credentials are test credentials and cannot be used in production. Use it during development and in your automated test pipeline.

The FATOORA simulation portal

The simulation portal, launched in December 2022, is a replica of the FATOORA portal accessed from the taxpayer's own login. It lets you rehearse the full journey, from generating OTPs and onboarding units to clearing and reporting documents, with dummy or historical data. Responses are not official clearance or reporting. Use it for end-to-end rehearsal with real organisational setup before go-live.

What your test plan should cover

• Every document type you issue, including credit and debit notes linked to original invoices.
• Rejections and warnings, and correct chain continuity after a rejected document.
• Network failures, timeouts and recovery of a backlog of unreported invoices.
• Certificate renewal without interrupting invoicing.
• Peak volumes, such as month-end batches or retail promotions.
• Arabic seller and buyer names, VAT numbers and addresses in all fields.

How should errors, warnings and outages be handled?

ZATCA's APIs return standard HTTP status codes, and each needs a defined response in your integration:

Response	Meaning	What your system should do
200	Accepted, cleared or reported	Store ZATCA's response and the cleared XML, then release the invoice
202	Accepted with warnings	Release the invoice, log the warnings and route them for correction in master data
303	Wrong flow, for example clearance is disabled	Resubmit the standard invoice to the reporting API as directed
400	Rejected because of validation errors	Fix the data and issue a new document with a new UUID, ICV and hash
500	Server error	Retry with exponential back-off, then alert if retries are exhausted

Design for interruption from day one. Use a persistent outbox or queue so no invoice is lost, make submissions idempotent, monitor queue depth against the 24-hour reporting window, and alert on rising rejection rates. The guideline also requires taxpayers to notify ZATCA of technical failures, and all transactions issued during downtime must later be cleared or reported in compliant XML. Invoicing must not stop the business, so your fallback procedure should be documented and rehearsed.

Should each system integrate directly or through a central service?

Organisations rarely have a single invoicing system. Branches, e-commerce platforms, subsidiaries, point-of-sale terminals and legacy billing tools may all issue invoices. The key architecture decision is whether each system integrates with ZATCA directly or whether a central e-invoicing service handles compliance for all of them.

• Direct integration suits a single modern ERP with built-in, vendor-supported ZATCA functionality.
• A central e-invoicing service suits mixed estates. Source systems send invoice data to one service that builds the XML, signs, submits and archives. Credentials, chaining logic and monitoring live in one place, and future specification changes are absorbed once.

Retail and hospitality businesses with many tills face specific questions about offline operation and per-device units; our guide to ZATCA-compliant POS systems covers them. If you are replacing your ERP at the same time, our ERP system guide explains how to evaluate built-in e-invoicing support.

What does a typical integration project look like?

1. Inventory. List every system and channel that issues invoices, credit notes or debit notes, and the data each holds.
2. Gap analysis. Compare available data, such as buyer VAT numbers, addresses and item tax categories, with ZATCA's required fields.
3. Architecture. Decide EGS unit boundaries, direct versus central integration, key storage and the queueing model.
4. Build and sandbox testing. Develop XML generation, signing, QR and API clients, and validate continuously with the SDK and sandbox.
5. Simulation rehearsal. Onboard units and run realistic scenarios on the simulation portal.
6. Production onboarding and go-live. Generate OTPs, obtain production CSIDs, switch over and monitor closely during the first billing cycles.

Next step

If your wave deadline is approaching, start with the inventory and gap analysis; data quality issues surface there, not in the API calls. Amwaj Solutions designs and builds e-invoicing integrations for ERP, billing and POS systems through our ZATCA e-invoicing integration service. Contact us to scope your integration.