ZATCA Phase 2 Integration: A Guide for POS and ERP
ZATCA Phase 2 links your invoicing system to FATOORA: B2B invoices are cleared before issue, B2C invoices reported within 24 hours, each as signed UBL XML.
ZATCA Phase 2, the integration phase of Saudi Arabia's e-invoicing program known as FATOORA, requires taxpayers to connect their invoicing systems to ZATCA's platform. Standard tax invoices issued to businesses must be cleared by ZATCA before they reach the buyer, and simplified tax invoices issued to consumers must be reported to ZATCA within 24 hours of being issued. Each invoice is produced as structured XML based on UBL 2.1, generated by a device or system onboarded with ZATCA, and linked to the invoices before it through a hash chain. ZATCA brings taxpayers into Phase 2 in waves and notifies each taxpayer of its integration date. RNDSOL builds Phase 2 integrations for POS and ERP systems used by businesses in Saudi Arabia, and this guide covers what the work involves for a software vendor or an in-house team. The specification is updated from time to time, so treat this as a map and confirm your wave date and the current technical documents on the ZATCA portal before you build.
What Is the Difference Between Clearance and Reporting?
Clearance applies to standard tax invoices, the B2B invoices a buyer uses to reclaim VAT. Your system builds the invoice XML and sends it to ZATCA's clearance API before the buyer sees it. ZATCA validates it and returns the cleared invoice, and only that cleared version is a valid invoice to share with the buyer. If clearance fails, the invoice has not been issued, so your system has to show the errors, let the user fix the data and try again. Reporting applies to simplified tax invoices, the B2C receipts from a shop counter, a restaurant or an e-commerce checkout. Your system signs the invoice, prints or sends it to the customer straight away with its QR code, and then reports it to ZATCA within 24 hours. That split matters for system design. A POS can keep selling during an internet outage, queue its simplified invoices and report them when the connection returns, as long as it stays inside the 24-hour window. An ERP issuing B2B invoices needs a live connection at the moment of issue, plus clear handling for the cases where ZATCA rejects an invoice. Credit notes and debit notes follow the same path as the invoice type they relate to.
What Does a Phase 2 Invoice Contain?
- XML based on UBL 2.1, following ZATCA's data dictionary and business rules, with the invoice type code that marks it as standard or simplified
- A UUID that identifies the invoice uniquely
- An invoice counter value that increases with every document a device issues
- The hash of the previous invoice from the same device, which chains invoices together so a deleted or altered one shows up
- A hash of the current invoice and a cryptographic stamp, made with the key and certificate issued to that device during onboarding
- A QR code on the invoice the customer receives, carrying the fields ZATCA specifies for Phase 2
- For human-readable copies, a PDF/A-3 file with the XML embedded is the usual format; confirm the current rules for which copy counts as the invoice
How Do Onboarding and the CSID Work?
Every e-invoice generation solution unit, which ZATCA calls an EGS unit, has to be onboarded before it can issue invoices. Depending on your setup, an EGS unit might be one POS terminal, one branch server or one ERP instance, and the choice affects how many units you onboard and how you manage their hash chains. The unit generates a key pair and a certificate signing request containing the taxpayer's details. A user with access to the taxpayer's FATOORA portal account generates a one-time password, and the unit submits the request with that password to receive a compliance CSID (cryptographic stamp identifier). With the compliance CSID, the unit must pass ZATCA's compliance checks by submitting sample invoices, credit notes and debit notes of each type it will issue. Once those pass, it requests a production CSID and can start issuing live invoices. Certificates expire and must be renewed, so the renewal flow belongs in the product, not in a runbook nobody opens. Private keys belong in secure storage on the device or server, never in source control or a shared spreadsheet, a point our posts on SAMA compliance and NCA ECC vs SAMA CSF cover for systems in regulated sectors.
What Must a POS or ERP Vendor Change?
The invoice data model usually changes first. Phase 2 needs fields that many systems do not store in structured form: buyer VAT number and address for standard invoices, the reason code on credit notes, the reference to the original invoice, and VAT category codes on every line. Next comes an XML builder that turns your invoice into compliant UBL, with a signing module that computes the hash, applies the stamp and generates the QR code. Each EGS unit needs a persistent counter and the last invoice hash, stored so that a crash, a restore from backup or two terminals sharing a database cannot break the chain. Then the API client: clearance calls for standard invoices, reporting calls for simplified ones, retries with backoff, and a queue that survives restarts. Your system has to store what ZATCA returns, including the cleared XML, warnings and rejection reasons, and show them to users in plain language. Finally, the onboarding and renewal flow for each device, plus an admin screen showing which units are onboarded, which certificates expire soon and which invoices are still waiting to be reported. For an existing POS or ERP with a clean invoice model, this is typically 6 to 10 engineer-weeks, about $8,400 to $22,000 at $1,400 to $2,200 per engineer-week. Multi-branch deployments, offline POS queues and messy legacy invoice data push it higher; our cost calculator gives a wider range if the integration is part of a larger rebuild.
How Do You Test a ZATCA Integration?
ZATCA publishes a developer portal with a sandbox for testing the APIs, along with an SDK that validates invoice XML, signatures and QR codes against the current rules. Use both early. Run every invoice your system can produce through the SDK as part of your automated tests, so a code change that breaks compliance fails the build instead of failing in production. Build a test matrix that covers standard and simplified invoices, credit and debit notes, zero-rated and exempt lines, discounts at line and document level, and invoices in foreign currency if you issue them. Test the failure paths deliberately: a rejected clearance, a timeout, a reporting queue that has been offline for 20 hours, a terminal restored from an old backup. Check the portal for the environments available at the time you build, because ZATCA has changed its testing tools as the rollout has progressed. Discovery for this work on our side takes one to two weeks and ends with the invoice field mapping, the EGS unit design, the test matrix and a fixed quote.
Which Wave Are You In, and When Do You Start?
ZATCA has rolled out Phase 2 in waves, each defined by a revenue threshold over a reference period, and it notifies the taxpayers in each wave ahead of their integration deadline. We are not listing wave dates or thresholds here, because ZATCA sets and updates them; check your own status on the FATOORA portal or with your tax advisor. If you sell software to Saudi businesses, assume your customers will arrive in later waves and build once, for all of them, rather than patching each deployment as notices come in.
Phase 2 Readiness Checklist
- Confirm your wave and integration deadline on the ZATCA portal, and read the current technical specifications rather than a summary
- Decide what counts as an EGS unit in your system and how many you will onboard
- Map every invoice field, including buyer details, VAT category codes and credit note references, to the UBL elements
- Store the invoice counter and previous hash per unit in a way that survives crashes, restores and concurrent terminals
- Keep private keys in secure storage, with an owner for certificate renewal
- Run the ZATCA SDK validator in your automated test suite
- Design for clearance failures on B2B invoices and for the 24-hour reporting window on B2C ones
- Give finance users a screen showing rejected, pending and reported invoices with the reasons in plain language
Have a project that needs this kind of thinking applied to it?