Complete Guide to Decoding ZATCA QR Codes
ZATCA (Zakat, Tax and Customs Authority) mandates that all electronic invoices in Saudi Arabia include a machine-readable QR code. This QR code contains essential invoice information encoded using the TLV (Tag-Length-Value) format and converted to Base64. Understanding how to decode these QR codes is crucial for invoice verification, audit compliance, and system integration.
Understanding TLV Encoding Structure
The ZATCA QR code uses a binary encoding scheme where each piece of data is structured as:
- Tag (1 byte): An integer from 1-9 identifying the data type
- Length (1 byte): The number of bytes in the value (max 255)
- Value (variable): The actual data, encoded in UTF-8 for Tags 1-7, or raw binary for Tags 8-9
After concatenating all TLV tuples, the resulting byte array is encoded to Base64, which is then rendered as the QR code image.
ZATCA QR Code Tags Explained
Phase 1 Tags (Mandatory since December 2021)
| Tag | Field | Format | Example |
|---|---|---|---|
| 1 | Seller Name | UTF-8 String | شركة المثال ذ.م.م |
| 2 | VAT Number | 15 digits (3...3) | 310122393500003 |
| 3 | Timestamp | ISO 8601 | 2024-01-15T14:30:00 |
| 4 | Invoice Total | Decimal | 1150.00 |
| 5 | VAT Amount | Decimal | 150.00 |
Phase 2 Tags (Additional Cryptographic Data)
| Tag | Field | Format | Purpose |
|---|---|---|---|
| 6 | XML Hash | Base64 (44 chars) | SHA-256 hash of invoice XML |
| 7 | ECDSA Signature | Base64 (~96 chars) | Digital signature of the hash |
| 8 | Public Key | DER Binary (Base64) | Key for signature verification |
| 9 | ZATCA Signature | Binary (Base64) | CA signature (simplified invoices) |
Decoding Process Step-by-Step
- Extract Base64: Scan the QR code to get the Base64 string
- Decode to bytes: Convert Base64 to a byte array using standard decoding
- Parse TLV tuples: Read Tag, Length, Value sequentially from the byte array
- Interpret values: Convert bytes to strings/numbers based on tag type
- Validate fields: Check format compliance (VAT format, timestamp, etc.)
Common Decoding Errors and Solutions
Troubleshooting Guide
- Invalid Base64: Ensure the complete QR content is captured. Partial scans will fail.
- TLV parsing error: The QR may use a non-ZATCA format. Verify it's from a ZATCA-compliant system.
- Missing Phase 2 tags: Phase 1 invoices only have Tags 1-5. Tags 6-9 require ZATCA integration.
- Corrupted signature: Binary data (Tags 8-9) must be handled as raw bytes, not UTF-8.
Integration with ZATCA E-Invoicing
For businesses operating in Saudi Arabia, understanding QR decoding is essential for:
- Invoice Verification: Validate received invoices before payment processing
- Audit Compliance: Ensure QR codes match invoice details during tax audits
- System Integration: Parse QR data for automated accounting workflows
- Customer Trust: Allow customers to verify invoice authenticity
Pro Tip: Verify with Official Tools
Always cross-check decoded QR data with the official ZATCA VAT App for production invoices. This decoder is perfect for development, testing, and understanding QR structure, but official validation should use ZATCA's approved channels.
Related Tools for ZATCA Compliance
Complete your e-invoicing toolkit with these complementary tools:
- ZATCA QR Generator - Create compliant QR codes for your invoices
- ZATCA XML Viewer - Visualize and understand invoice XML structure
- ZATCA Readiness Checker - Assess your Phase 2 compliance status