ZATCA E-Invoicing Technical Requirements: UBL XML, CSID and QR Codes
Saudi Arabia’s Zakat, Tax and Customs Authority (ZATCA) has mandated a phased transition to electronic invoicing under the Fatoora framework. This article covers the technical requirements every business must meet: UBL 2.1 XML structure, CSID generation and management, cryptographic stamping, the 9-tag TLV base64 QR code, and the clearance versus reporting API distinction.
Overview of the ZATCA E-Invoicing Framework
The ZATCA e-invoicing regime applies to all taxpayers subject to VAT in Saudi Arabia. It distinguishes between two phases:
- Phase 1 (Generation): commenced 4 December 2021 – required all taxpayers to generate and store structured e-invoices.
- Phase 2 (Integration): commenced 1 January 2023 (wave 1) and continues in waves through 2026 – requires taxpayers above specified revenue thresholds to connect to ZATCA’s platform and submit invoices via API.
For Phase 2, taxpayers must use either the clearance model (for standard invoices) or the reporting model (for simplified invoices and debit/credit notes). Both models require UBL XML format, a valid CSID, and a compliant QR code.
UBL 2.1 XML Structure
Universal Business Language (UBL) 2.1 is the mandatory XML schema for ZATCA e-invoices. The invoice XML must follow the structure defined in ZATCA’s technical specifications. Key elements include:
| UBL Element | Description | Mandatory |
|---|---|---|
cbc:UBLVersionID | Must be 2.1 | Yes |
cbc:CustomizationID | Identifies the ZATCA profile | Yes |
cbc:ID | Invoice number (unique per seller) | Yes |
cbc:IssueDate | Date of issue (ISO 8601) | Yes |
cbc:IssueTime | Time of issue (UTC+3) | Yes |
cac:AccountingSupplierParty | Seller details (name, VAT number, address) | Yes |
cac:AccountingCustomerParty | Buyer details | Yes |
cac:TaxTotal | Tax amounts per VAT category (standard/zero/exempt) | Yes |
cac:LegalMonetaryTotal | Total invoice amounts | Yes |
cac:InvoiceLine | Line items (at least one) | Yes |
cbc:AdditionalDocumentReference | QR code and cryptographic stamp | Yes |
CSID Generation and Management
A Compliance Cryptographic Stamp Identifier (CSID) is the digital certificate that identifies the taxpayer in the ZATCA e-invoicing ecosystem. There are two types:
- Compliance CSID: Issued during the onboarding process; used for testing and compliance validation.
- Production CSID: Issued after successful compliance checks; used for live invoice submission.
The CSID is tied to the taxpayer’s VAT registration number and includes a public-private key pair. The process of obtaining a CSID involves:
- Generate a Certificate Signing Request (CSR) using a tool compliant with ZATCA specifications.
- Submit the CSR to ZATCA via the onboarding API.
- ZATCA validates the request and issues a Compliance CSID.
- Submit a sample invoice for compliance validation.
- Upon approval, ZATCA issues the Production CSID.
Cryptographic Stamp
Every e-invoice submitted to ZATCA must include a cryptographic stamp (also called an e-invoice signature). The stamp serves as proof of integrity and authenticity. It is generated by signing a specific set of invoice fields using the taxpayer’s private key (from the CSID). ZATCA verifies the stamp using the public key embedded in the CSID.
The cryptographic stamp is embedded in the XML as a signed property under cac:AdditionalDocumentReference. The stamp must be recalculated by the buyer for clearance invoices (dual signing).
9-Tag TLV Base64 QR Code
All e-invoices (whether standard or simplified) must display a QR code that encodes specific invoice data using the TLV (Tag-Length-Value) format, encoded in base64. The QR code contains exactly nine tags:
| Tag ID | Data Field | Example Value |
|---|---|---|
| 1 | Seller’s name | ACME Trading Co. |
| 2 | VAT number of seller | 310123456700003 |
| 3 | Invoice timestamp (ISO 8601) | 2025-06-15T14:30:00Z |
| 4 | Invoice total (with VAT) | 1150.00 |
| 5 | Total VAT amount | 150.00 |
| 6 | Hash of the invoice XML (before signing) | a1b2c3d4e5f6… |
| 7 | Digital signature (seller crypto stamp) | sig_a1b2c3d4… |
| 8 | Public key of the seller (from CSID) | MIIBIjANBgkqhki… |
| 9 | Signature type | 1 (for ZATCA signing) |
The QR code must be rendered on the invoice PDF (or printed format) and must be scannable using any standard QR reader. The TLV encoding is built sequentially: Tag 1, Length, Value; Tag 2, Length, Value; and so on, then encoded as base64.
Clearance vs. Reporting APIs
ZATCA provides two API models for invoice submission, depending on the invoice type.
| Aspect | Clearance | Reporting |
|---|---|---|
| Applies to | Standard invoices (B2B) | Simplified invoices (B2C) and debit/credit notes |
| Process | Invoice submitted to ZATCA before it is sent to the buyer; ZATCA validates and returns a clearance result (passed/rejected) | Invoice submitted to ZATCA after it is issued to the customer; ZATCA records it without blocking |
| API endpoint | /compliance/clearance | /compliance/reporting |
| Response | Clearance status and signed invoice (if passed) | Reporting acknowledgement |
| Invoice status | Invoice is not valid until cleared by ZATCA | Invoice is valid upon generation; reporting is retrospective |
| Latency requirement | Near real-time (sub-second expected) | Within 24 hours of issuance |
Invoice Submission Process
The end-to-end process for submitting a standard invoice to ZATCA under the clearance model is as follows:
- Generate the invoice in UBL 2.1 XML format.
- Calculate the hash of the invoice XML (SHA-256).
- Sign the hash with the seller’s private key to create the cryptographic stamp.
- Encode the 9-tag TLV QR code and embed it in the XML.
- Optionally, the buyer may countersign the invoice (dual signing).
- Submit the signed XML to ZATCA’s clearance API.
- ZATCA validates the XML structure, CSID, stamp, and QR code.
- ZATCA returns a clearance response: either a passed (with ZATCA countersignature) or rejected (with error codes).
- If passed, deliver the cleared invoice to the buyer (including the ZATCA stamp).
- Store the invoice and all metadata for the statutory record-keeping period.
Compliance Checks
ZATCA performs both automated and manual compliance checks. Automated checks include:
- XML schema validation against UBL 2.1 and ZATCA extensions.
- CSID validity (not expired, not revoked).
- Cryptographic stamp verification (integrity check).
- QR code decodability and data accuracy.
- VAT calculation consistency across line items, totals, and the QR code.
- Duplicate invoice check (UUID and invoice number).
Manual compliance audits may be triggered for taxpayers with a history of rejected invoices or unusual patterns. Non-compliant invoices attract penalties ranging from SAR 5,000 to SAR 50,000 per violation.
FAQ
Do I need to generate the QR code in the XML itself or only on the PDF?
The QR code data must be included as an embedded binary in the XML (under cac:AdditionalDocumentReference) and also rendered on the PDF or printed invoice. Both representations must match exactly.
What happens if my CSID expires?
Invoices submitted with an expired CSID will be rejected by ZATCA. You must renew your CSID before its expiry date using the renewal API. The production CSID typically has a validity period aligned with your VAT registration.
Can I use an external e-invoicing solution, or must I build my own?
ZATCA does not mandate a specific solution. You can build your own, license third-party software, or use a cloud e-invoicing provider. The solution must meet all technical specifications, regardless of origin.
What is the difference between a simplified and a standard invoice in technical terms?
Simplified invoices use the Invoice type but with fewer mandatory fields (e.g. buyer details are optional or simplified). They use the reporting API, not the clearance API. The QR code structure is identical for both types.
How is dual signing implemented?
For clearance invoices, the buyer must countersign the seller’s signed invoice hash using the buyer’s own CSID private key. This produces a second signature embedded in the XML. The dual signature confirms both parties acknowledge the invoice.
What penalty applies for submitting invoices late?
Late submission of clearance invoices (submitting after the invoice is sent to the buyer) or late reporting can result in a penalty of SAR 5,000 per invoice. ZATCA publishes updated penalty schedules on its portal.
How Bitrixme Can Help
Bitrixme provides end-to-end ZATCA e-invoicing compliance support. From CSID onboarding and UBL XML generation to API integration and QR code implementation, our technical team ensures your invoicing system meets Fatoora requirements.
