ZATCA E-Invoicing Phase 2: Fatoora Sandbox Testing Guide

If your organisation is approaching its ZATCA Phase 2 wave date and you still have not completed Fatoora sandbox testing, you are already behind. The integration is not a one-day task — ZATCA's onboarding sequence has six distinct technical stages, each with its own failure modes, and the sandbox is the only place to surface them before they block live clearance.

This guide cuts through the high-level compliance summaries you have already read and goes straight to what your accounting and ERP team needs to do, in order, with the right citations to verify against.

Why Phase 2 Is a Different Beast from Phase 1

Phase 1 (Generation Phase) required taxpayers to generate structured e-invoices in XML or PDF/A-3 format with embedded XML and store them. No real-time transmission, no ZATCA involvement at the point of sale.

Phase 2 (Integration Phase) adds two live obligations under ZATCA's E-Invoicing Implementing Regulation, Article 53:

• Clearance — Standard tax invoices (B2B) must be submitted to the Fatoora platform and receive a ZATCA cryptographic stamp before they are shared with the buyer.
• Reporting — Simplified invoices (B2C) must be reported to ZATCA within 24 hours of generation.

The commercial consequence is immediate: an uncleaned B2B invoice cannot legally serve as a VAT input tax credit document for your buyer. If your ERP pushes uncertified invoices, your clients' deductible VAT is at risk — not just yours.

ZATCA's official portal for all e-invoicing documentation is zatca.gov.sa.

The Fatoora Sandbox: What It Is and What It Tests

The Fatoora sandbox is ZATCA's pre-production environment, accessible via the same API endpoints as production but pointed at test infrastructure. It validates:

1. XML structure against UBL 2.1 with ZATCA KSA extensions (KSA-EN16931-01 and KSA-EN16931-02 business rules)
2. Cryptographic Stamp (CSID) provisioning — your ERP must generate a compliant Certificate Signing Request (CSR)
3. QR code encoding (TLV format, 8 mandatory fields for standard invoices)
4. API call sequence — onboarding → compliance check → CSID issuance → clearance/reporting

Passing the sandbox does not automatically activate production. You still need to complete the production onboarding API call with your live CSID before go-live.

Fatoora Sandbox Onboarding: Step-by-Step

Step 1 — Generate a Compliant CSR

Your ERP or middleware must generate a CSR embedding the following custom OIDs mandated by ZATCA:

OID	Field	Example Value
2.16.682.1.1.1.1.3.4	Environment Identifier	NonProductionCSID
2.16.682.1.1.1.1.3.3	Solution Name	ERP_Vendor_Name
2.16.682.1.1.1.1.3.2	VAT Registration Number	3101234567890003
2.16.682.1.1.1.1.3.1	Unit	Riyadh HQ

A missing or malformed OID is the single most common reason the sandbox rejects a CSR at first submission. Confirm these with your ERP vendor against the ZATCA E-Invoicing SDK documentation published on the portal.

Step 2 — Call the Compliance CSID API (Onboarding)

Endpoint (sandbox): POST /compliance

Pass the Base64-encoded CSR in the request body. A successful response returns a requestID and a Compliance CSID (a temporary certificate valid only for sandbox compliance checks). Store both — you will need the requestID to call the next endpoint.

If you receive a 400 error at this stage, the CSR OIDs are almost certainly the problem. If you receive a 500, the issue is likely with certificate chain trust — ensure your ERP trusts ZATCA's intermediate CA certificate.

Step 3 — Submit a Compliance Invoice

With the Compliance CSID in hand, submit a sample invoice to POST /compliance/invoices. This is where your XML is validated against all KSA business rules. ZATCA returns a structured warnings/errors array.

Critical rules to clear before you even hit the sandbox:

• BR-KSA-26: Invoice UUID must be unique per device
• BR-KSA-44: Seller's VAT number must match the CSID certificate
• BR-KSA-61: Cryptographic hash of the previous invoice must be embedded (chaining)
• BR-KSA-66: Digital signature must cover the canonical XML

A practical tip: run your XML through the ZATCA E-Invoicing Validator (available as a desktop tool via the portal) locally before hitting the sandbox API. This saves API call quota and speeds up your debug cycle significantly.

Step 4 — Obtain the Production CSID

Once compliance checks pass, call POST /production/csids using your requestID. This endpoint issues your Production CSID, which is the certificate your ERP signs live invoices with.

This certificate has a validity period. Track the expiry date — certificate renewal requires repeating the onboarding sequence. Build a calendar reminder into your compliance calendar for 30 days before expiry.

Step 5 — Test Clearance and Reporting Flows

With the Production CSID (still pointing at sandbox), test your actual clearance and reporting calls:

• Clearance (POST /invoices/clearance/single): Submit your signed, hashed XML. You should receive a 200 with a ZATCA-stamped invoice in the response.
• Reporting (POST /invoices/reporting/single): Submit your simplified invoice XML. Expect a 202 Accepted for async processing.

Test at minimum: a standard tax invoice, a credit note, a debit note, and a simplified invoice. Edge cases like invoices with multiple VAT categories (standard-rated, zero-rated, exempt line items on the same invoice) are where most implementations break.

Saudi E-Invoicing Onboarding Checklist

Before you request your production wave date from ZATCA, confirm every item:

• ERP is Mu'tamad-listed or has passed ZATCA's technical review
• CSR generation includes all four custom OIDs, correct environment identifier
• VAT registration number on the CSR matches ZATCA records exactly (15 digits)
• Invoice UUID generation is device-specific and collision-resistant
• Previous invoice hash chaining is implemented and tested across day-boundary resets
• QR code encodes all 8 TLV fields for standard invoices; 5 TLV fields for simplified
• XML timestamp uses UTC+3 (AST) formatted as YYYY-MM-DDTHH:MM:SS
• Compliance CSID tests return zero errors (warnings are acceptable for go-live)
• Production CSID expiry date is in your compliance calendar
• Finance team briefed on the 24-hour reporting window for simplified invoices

Common Integration Failures and How to Fix Them

Hash mismatch on invoice chain (BR-KSA-61) — Almost always caused by the ERP storing the previous invoice hash as a string and recomputing the hash at clearance time rather than storing the raw hash bytes. Confirm with your developer that the chaining stores the SHA-256 hex output verbatim.

Signature validation failure (BR-KSA-66) — Usually a canonical XML (C14N) issue. The digital signature must be applied to the canonicalised XML, not the serialised string your application happens to produce. This is a developer fix, not an accountant fix — but you need to know enough to push back when the vendor says "it's fine."

24-hour reporting breach — If your POS system is offline (common in retail), your reporting clock is still running from invoice generation time, not from when connectivity resumes. Article 53 of the Implementing Regulation does not provide a connectivity exception. Build an offline queue with a hard alert at the 20-hour mark.

VAT rounding errors — ZATCA's rules require per-line VAT calculation rounded to 2 decimal places, with the invoice-level VAT being the sum of line-level figures, not an independent calculation of 15% × net total. A ﷼1,000,000 invoice can produce a ﷼1–2 discrepancy this way that triggers a validation error.

What Accountants (Not Just Developers) Must Own

The integration is technical, but the compliance exposure is yours. Three ownership areas belong to the accounting function regardless of who writes the code:

1. CSID lifecycle management — Certificate expiry causes your ERP to stop clearing invoices entirely. This is an operational risk item for your month-end close calendar.
2. Credit note linkage — Under ZATCA rules, a credit note must reference the original cleared invoice UUID. If your team manually raises credit notes outside the ERP, those documents will fail clearance. Enforce the ERP workflow without exceptions.
3. Audit trail for the 6-year retention period — Phase 2 invoices carry a ZATCA cryptographic stamp. Your archiving system must preserve the stamped XML, not just a PDF rendition of it. Confirm this with your document management vendor now.

If you want to test your own technical understanding of the Phase 2 workflow before your next vendor call, the SuperAccountant quiz has a dedicated e-invoicing module that covers ZATCA's business rules in scenario format.

Your Next 30 Days

If your wave date is within the next quarter, work backwards from go-live and assign dates to each sandbox stage. Most implementations that fail their wave date do so because sandbox testing started too late to iterate through XML errors and CSR rejections before the compliance window closes. ZATCA does grant wave date extensions, but they must be formally requested and are not guaranteed.

Keep the official ZATCA portal bookmarked: all SDK downloads, API specifications, and wave date schedules are published at zatca.gov.sa. Do not rely on third-party summaries — the specs update frequently and version mismatches are a direct source of sandbox failures.

---

Sharpen your edge with SuperAccountant's next live cohort — small batches, real client workpapers, taught by partners. Details and seats at https://app.superaccountant.in/en/cohort.