ZATCA’s Phase 2 (Integration Phase) requires every e-invoicing system in Saudi Arabia to connect to the Fatoora platform. Standard tax invoices must be cleared by ZATCA before they reach your customer, and simplified invoices must be reported within 24 hours.
With Wave 25 bringing businesses above SAR 187,500 in revenue into Phase 2 by 1 February 2027, many ERPNext users are now facing onboarding for the first time. The process is very doable, but it has to happen in a specific order, and a few small mistakes can stop it completely.
This guide walks through ZATCA Phase 2 integration for ERPNext step by step, from preparing your data to issuing your first cleared invoice.
New to Phase 2 or not sure if you’re included? Start with our ZATCA Wave 25 guide.
Key Takeaways
ERPNext needs a ZATCA compliance app to produce Phase 2 invoices and connect to Fatoora.
Onboarding follows a fixed sequence: OTP → CSR → compliance CSID → compliance checks → production CSID.
Every invoicing unit (company, branch or POS device) needs its own CSID.
OTPs expire after one hour, so generate them only when you’re ready.
You must pass compliance checks for every invoice type you configure.
Clean company, customer and item data prevents most onboarding errors.
How ZATCA Phase 2 Works with ERPNext
ERPNext creates the invoice as it does today.
The ZATCA app converts it into ZATCA-compliant UBL 2.1 XML, with a UUID, invoice hash, previous invoice hash and cryptographic stamp.
Standard tax invoices (B2B) are sent to ZATCA for clearance. Only after clearance is the invoice shared with the buyer.
Simplified tax invoices (B2C) are given to the customer immediately and reported to ZATCA within 24 hours.
ZATCA’s response (cleared, reported, warning or rejected) is saved against each invoice in ERPNext.
ZATCA’s Three Environments
Environment | Used for |
|---|---|
Developer portal (sandbox) | Technical testing during development, without real taxpayer data |
Simulation | Rehearsing onboarding and invoice submission with your real details |
Production | Live invoicing |
Always rehearse in simulation before onboarding production.
Step 1: Install a ZATCA Compliance App for ERPNext
Standard ERPNext doesn’t connect to Fatoora on its own. You’ll need a ZATCA Phase 2 app. Several exist, both open source and commercial. Check that the app you choose:
Supports both clearance and reporting
Handles standard and simplified invoices, credit notes and debit notes
Supports multiple companies, branches and POS profiles
Handles onboarding, compliance checks and CSID renewal
Stores ZATCA responses and status on each invoice
Supports your ERPNext version
Step 2: Prepare Your Company Data
ZATCA validates seller details on every invoice. In ERPNext, check each company has:
15-digit VAT number (starts and ends with 3)
Legal name in Arabic (and English if used)
Commercial registration (CR) number or other seller ID
Full national address: building number, street, district, city, postal code and additional number
Correct country code (SA)
Step 3: Prepare Customer Data
For standard tax invoices (B2B), buyer details must be complete:
Buyer VAT number (if VAT-registered)
Buyer legal name
Buyer national address with building number, district, city and postal code
Another buyer ID where no VAT number exists (such as CR number), where required
Customer type set correctly, so ERPNext knows whether to issue a standard or simplified invoice
Missing buyer address fields are one of the most common reasons standard invoices fail clearance.
Step 4: Prepare Items and Taxes
Every item has the right VAT category: standard-rated (15%), zero-rated, exempt or out of scope
Exemption and zero-rating reason codes set for non-standard items
ERPNext tax templates match ZATCA’s VAT categories
Discounts and charges set up so line totals and invoice totals calculate exactly
Invoice print formats show the required Arabic fields and QR code
Step 5: Decide Your Invoicing Units
Each unit that issues invoices needs its own onboarding and CSID. In ERPNext, a unit is typically:
A company issuing invoices from the desk
A branch with its own invoicing
A POS profile or device issuing simplified invoices
Decide for each unit which invoice types it issues:
Invoice type code | Unit issues |
|---|---|
| Standard tax invoices only (B2B) |
| Simplified tax invoices only (B2C) |
| Both standard and simplified |
This code goes into the CSR, and it decides which compliance checks you must pass.
Tip: each unit keeps its own invoice counter and hash chain. Keep units stable; avoid creating and deleting POS profiles once you’re live.
Step 6: Generate an OTP in the Fatoora Portal
Log in to the Fatoora portal with your ZATCA credentials.
Choose Onboard new solution unit/device.
Generate OTP codes, one per unit you’re onboarding.
Copy the OTP into your ERPNext ZATCA app right away.
OTPs are valid for only one hour. Prepare everything in Steps 2 to 5 before generating them.
Step 7: Generate the CSR
Your ZATCA app creates a certificate signing request (CSR) for each unit, including:
Field | What it contains |
|---|---|
Country | SA |
Organization | Your taxpayer name |
Organizational unit | Branch name, or the 10-digit TIN for VAT groups |
Common name | Your unit’s name or identifier |
Serial number | Solution name, version and unit identifier |
UID | Your 15-digit VAT number |
Title | Invoice type code (1000, 0100 or 1100) |
Registered address | The unit’s location |
Business category | Your industry |
Simulation and production use different certificate templates, so make sure the app is set to the right environment.
Step 8: Get the Compliance CSID
The app sends the CSR and OTP to ZATCA’s compliance endpoint. ZATCA returns a Compliance CSID (CCSID): a temporary certificate and secret used only for compliance testing. The app stores it for the next step.
Step 9: Pass the Compliance Checks
Before you can go live, the unit must submit sample documents that pass ZATCA’s validation:
Invoice type code | Required samples |
|---|---|
| Standard tax invoice, standard debit note, standard credit note |
| Simplified tax invoice, simplified debit note, simplified credit note |
| All six |
Your ZATCA app usually generates and submits these for you. If any fail, fix the cause in your company, customer, item or tax data and run the checks again.
Step 10: Get the Production CSID
Once every required sample passes, the app requests a Production CSID (PCSID) using the compliance request and CCSID. The PCSID is the certificate the unit uses for live invoicing.
You can review issued CSIDs in the Fatoora portal under Review Existing Cryptographic Stamp Identifier.
Step 11: Go Live
Issue a standard invoice to a VAT-registered customer and confirm it’s cleared
Issue a simplified invoice (or POS sale) and confirm it’s reported
Issue a credit note against an existing invoice
Check that the QR code prints correctly on simplified invoices
Confirm ZATCA’s response is saved on each invoice in ERPNext
Step 12: Monitor and Maintain
Review rejected and warning responses daily for the first few weeks
Fix rejections at the source data, not just on the invoice
Make sure simplified invoices are reported within 24 hours, including after internet outages
Track CSID expiry and renew certificates before they expire
Onboard new branches or POS devices before they start issuing invoices
Common Onboarding and Clearance Errors
Problem | Likely cause | Fix |
|---|---|---|
OTP rejected | OTP older than one hour | Generate a new OTP and use it immediately |
CSR rejected | Wrong VAT number, invoice type code or environment template | Check CSR fields and environment |
Compliance check fails | Missing seller or buyer details, wrong tax category | Complete national address, VAT numbers and item tax setup |
Standard invoice not cleared | Buyer address or ID incomplete | Complete buyer national address and VAT or other ID |
Totals rejected | Rounding or discount calculation differences | Align line and invoice rounding with ZATCA rules |
Hash or counter errors | Invoices deleted or units changed after going live | Never delete submitted invoices; keep units stable |
Credit note rejected | Not linked to original invoice | Create credit notes against the original invoice |
Simplified invoices not reported | Connection outage | Make sure the app queues and retries reporting |
Onboarding Checklist
ZATCA app installed and tested in simulation
Company VAT number, Arabic name, CR number and national address complete
Customer VAT numbers, IDs and national addresses complete
Item VAT categories and exemption reasons set
Tax templates and print formats ready
Invoicing units and invoice type codes decided
OTPs generated only when ready (valid one hour)
CSR generated with correct fields and environment
Compliance CSID received
All required compliance checks passed
Production CSID received for every unit
First standard invoice cleared and simplified invoice reported
Daily monitoring and CSID renewal tracking in place
What About Odoo Users?
Odoo users follow the same ZATCA sequence (OTP, CSR, compliance checks, production CSID), using Odoo’s Saudi localization or a partner module. Comparing platforms? See ERPNext vs Odoo.
Frequently Asked Questions
Does ERPNext support ZATCA Phase 2?
Yes, with a ZATCA compliance app. The app generates compliant XML invoices, handles onboarding and CSIDs, and manages clearance and reporting with Fatoora.
What is the ZATCA onboarding process?
Generate an OTP in the Fatoora portal, create a CSR, obtain a compliance CSID, pass compliance checks with sample documents, then obtain a production CSID for live invoicing.
How long is a ZATCA OTP valid?
One hour after it’s generated. Generate OTPs only when your system and data are ready.
What compliance checks does ZATCA require?
It depends on the invoice types in your CSR. Units issuing standard invoices must pass a standard invoice, debit note and credit note; units issuing simplified invoices must pass the simplified versions; units issuing both must pass all six.
Does each POS or branch need its own CSID?
Yes. Every unit that issues invoices must be onboarded separately and receive its own CSID.
What’s the difference between a compliance CSID and a production CSID?
A compliance CSID is a temporary certificate used to run compliance checks. A production CSID is issued after the checks pass and is used for live invoicing.
Why was my standard invoice rejected?
The most common causes are incomplete buyer details (especially the national address), wrong VAT categories, rounding differences, or credit notes not linked to the original invoice.
Get ZATCA Phase 2 Live on ERPNext
Bizloom ERP helps businesses in Saudi Arabia implement ZATCA Phase 2 on ERPNext, working remotely with teams across the Kingdom. We can:
Choose, install and configure a ZATCA app for ERPNext
Clean company, customer and item data for successful validation
Onboard every company, branch and POS unit
Run compliance checks and obtain production CSIDs
Set up monitoring, retries and CSID renewal
Support you after go-live
Learn more about our ZATCA e-invoicing services and ERP in Saudi Arabia, or read our complete ZATCA e-invoicing guide. Operating across the Gulf? See our UAE ERPNext checklist and Fawtara guide for Oman.
Stuck on ZATCA onboarding? Message us on WhatsApp with the error you’re seeing. Ask on WhatsApp
Want a full readiness check? Book a Free ERP Assessment with Bizloom ERP.