ZATCA QR Code Generator

Complete Guide to ZATCA QR Code Compliance

To build a ZATCA-compliant QR code generator, your tool must adhere to strict technical specifications regarding data structure (TLV), encoding (Base64), and phase-specific mandatory fields. The QR code is a machine-readable matrix barcode that allows stakeholders and customers to validate the authenticity and integrity of electronic invoices and notes.

1. Mandatory Data Fields (Content)

The information contained in the QR code depends on whether the establishment is operating under Phase 1 (Generation) or Phase 2 (Integration).

Phase 1: Generation Phase (Mandatory since Dec 4, 2021)

For Simplified Tax Invoices (B2C), the QR code must contain the following five fields:

1. Seller’s Name: The legal name of the entity.
2. VAT Registration Number: The 15-digit number of the seller.
3. Timestamp: The date and time the invoice was issued, formatted according to ISO 8601 (e.g., 2022-02-21T12:13:57).
4. Invoice Total: The total amount of the invoice, inclusive of VAT.
5. VAT Total: The total value-added tax amount charged.

Phase 2: Integration Phase (Rolling out in waves since Jan 1, 2023)

In Phase 2, the QR code requirements are enhanced to include cryptographic security features. For all types of electronic invoices, the following additional fields (Tags 6–9) are mandatory:

• Tag 6: XML Hash: The hash of the invoice XML file.
• Tag 7: ECDSA Signature: The digital signature of the XML hash.
• Tag 8: ECDSA Public Key: The public key used to generate the signature.
• Tag 9: ZATCA Signature: For simplified invoices, the ECDSA signature of the cryptographic stamp issued by ZATCA’s Technical CA.

Note: For Standard Tax Invoices (B2B) in Phase 2, ZATCA’s Fatoora portal will generate the QR code string during the Clearance process and return it to the taxpayer to be visualized on the human-readable invoice.

2. Technical Encoding Architecture

Your tool must follow a specific sequence of operations to ensure the QR code can be parsed by ZATCA’s validation systems:

1. Tag-Length-Value (TLV) Formatting:
   • Tag: A single byte representing the tag number (e.g., 1 for Seller’s Name).
   • Length: A single byte representing the length of the value in bytes.
   • Value: The actual data bytes encoded in UTF-8.
2. Concatenation: Construct the TLV tuple for each required field and append them into a single continuous byte array.
3. Base64 Encoding: The final concatenated byte array must be encoded into a Base64 ASCII string.
4. Image Generation: Convert the resulting Base64 string into the QR image.

3. Implementation Constraints and Compliance

• Anti-Tampering: The system must prevent manual modification of the timestamp or invoice counter.
• Bilingual Visibility: The printed invoice must be in Arabic (English is optional).
• Validation: Verify generated QR codes using the official ZATCA VAT App.
• Cryptographic Keys: Private keys for ECDSA signatures must be non-exportable and stored securely.