ZATCA Phase 2 Setup
ZATCA (Zakat, Tax and Customs Authority) Phase 2 is Saudi Arabia's Integration Phase for e-invoicing. Under this regulation, businesses must generate e-invoices in a structured XML format, digitally sign them with a cryptographic stamp, and submit them to ZATCA's systems for clearance (B2B) or reporting (B2C). Shaari handles this entire process once you complete the setup described on this page.
ZATCA Phase 2 integration is available on the Enterprise plan. The ZATCA settings card appears in Settings > Integrations only after the feature has been enabled for your tenant.
Prerequisites
Before starting ZATCA setup, ensure the following are in place:
- Enterprise plan --- Your tenant must be on the Enterprise subscription.
- VAT registration --- Your company must have a valid 15-digit VAT registration number entered in Account Settings.
- Company information --- Your company name, address, and CR number must be complete in Account Settings.
- ZATCA portal account --- You need access to ZATCA's Fatoora portal to complete certain onboarding steps.
Do not attempt ZATCA onboarding with incomplete company information. The CSR generation and CSID issuance depend on accurate VAT, CR, and address data. Errors at this stage can require you to restart the process.
Enabling ZATCA for Your Tenant
ZATCA integration requires two configuration flags to be active:
- Feature gate --- The ZATCA Phase 2 feature must be enabled for your tenant. This is typically handled during Enterprise plan activation or by contacting Shaari support.
- ZATCA configuration --- Once the feature gate is active, the ZATCA settings card appears in your Settings, and you can begin the onboarding process.
When both flags are active, the ZATCA integration card appears under Settings > Integrations.
Environment Selection
Before generating certificates, select which ZATCA environment you want to connect to:
| Environment | Purpose |
|---|---|
| Sandbox | A test environment for development and initial testing. Invoices submitted here are not real. |
| Simulation | A pre-production environment that mirrors production behavior. Use this for final validation before going live. |
| Production | The live ZATCA system. Invoices submitted here are legally binding and reported to ZATCA. |
Start with the Sandbox environment to test your integration without any risk. Once you have verified that invoices are being generated and submitted correctly, move to Simulation for final validation, and then to Production when you are ready to go live.
CSR Generation
The first technical step in ZATCA onboarding is generating a Certificate Signing Request (CSR). The CSR contains your business information and is used to obtain your compliance certificate from ZATCA.
Shaari generates the CSR automatically based on the company information in your Account Settings. The process:
- Navigate to Settings > ZATCA Setup.
- Click Generate CSR.
- Shaari creates a CSR using your company's VAT number, CR number, and registered address.
- The CSR is submitted to ZATCA's API to obtain a Compliance CSID (Cryptographic Stamp Identifier).
Compliance CSID and Production CSID
The onboarding process involves obtaining two CSIDs:
Compliance CSID
The Compliance CSID is issued by ZATCA after they validate your CSR. It is used during the testing and validation phase to sign sample invoices and verify that your system produces compliant output.
Production CSID
Once compliance testing is complete, ZATCA issues a Production CSID. This is the certificate used to sign real invoices in the production environment. The Production CSID is what makes your invoices legally valid under ZATCA Phase 2.
Onboarding Steps
Shaari guides you through a 5-step onboarding process:
Step 1: Company Information Verification
Verify that your company name, VAT number, CR number, and address are correct. These details are pulled from your Account Settings.
Step 2: CSR Generation
Generate the Certificate Signing Request. Shaari handles the technical details --- you just confirm and proceed.
Step 3: Compliance CSID Issuance
Submit the CSR to ZATCA and receive the Compliance CSID. This step involves communication with ZATCA's API.
Step 4: Compliance Testing
Submit sample invoices to ZATCA using the Compliance CSID. This validates that your invoices meet all formatting, signing, and content requirements. Shaari runs these tests automatically.
Step 5: Production CSID Issuance
After passing compliance testing, request the Production CSID from ZATCA. Once issued, your tenant is fully onboarded and ready to submit real invoices.
Each step must be completed in order. You cannot skip ahead or return to a previous step without restarting the process. The onboarding progress is saved, so you can pause and resume at any time.
Testing with Sandbox Environment
The sandbox environment is ideal for initial testing. When connected to the sandbox:
- You can create and submit invoices without any legal implications.
- ZATCA's sandbox API validates your invoice format and returns detailed error messages if anything is wrong.
- You can test all invoice types: standard invoices, credit notes, debit notes, and simplified invoices.
- QR codes are generated but are not legally valid.
Use the sandbox to verify:
- Invoice XML structure is correct.
- Digital signatures are applied properly.
- QR codes encode the required TLV tags.
- Credit and debit notes reference their original invoices correctly.
Going Live with Production
When you are confident that your setup is correct:
- Complete the 5-step onboarding process using the production environment.
- Obtain your Production CSID.
- Shaari will automatically use the Production CSID to sign all subsequent invoices.
- Every approved invoice is submitted to ZATCA:
- B2B invoices go through the clearance process --- ZATCA validates and stamps the invoice before it reaches the buyer.
- B2C invoices go through the reporting process --- the invoice is reported to ZATCA within 24 hours.
Once you switch to production, every approved invoice is submitted to ZATCA as a legally binding document. Ensure your company information, VAT number, and invoice templates are all correct before going live. Corrections after submission require issuing credit or debit notes.