ZATCA QR Code Requirements & TLV Encoding: A Technical Guide

Understanding ZATCA QR Code Requirements

In the Saudi Arabian business landscape, the QR code on an e-invoice is far more than a simple shortcut to a website. It is a sophisticated, encoded data structure mandated by the Zakat, Tax and Customs Authority (ZATCA). Whether you are in Phase 1 (Generation) or Phase 2 (Integration), ensuring your QR code complies with the TLV (Tag-Length-Value) encoding standard is critical to avoiding fines and invoice rejections.

Incorrect QR codes are among the most common reasons for ZATCA invoice rejection errors. This guide breaks down the technical requirements of QR codes and how to implement them correctly.

What is TLV Encoding?

ZATCA requires QR code data to be formatted using the TLV (Tag-Length-Value) method before being converted into a Base64 string. This ensures that the data is compact, structured, and easily readable by the Fatoora simulation and production environments.

The Anatomy of TLV

1. Tag: A unique identifier for the data field (e.g., Tag 1 for Seller Name).
2. Length: The number of bytes in the value field.
3. Value: The actual data (e.g., “Qeemah Software”).

Required Fields for Phase 1 (Simplified & Standard Invoices)

For Phase 1, the QR code must contain the following five tags:

Tag	Field Name	Description
1	Seller Name	The legal name of the entity as registered with ZATCA.
2	VAT Number	The 15-digit VAT registration number of the seller.
3	Timestamp	The date and time the invoice was issued (ISO 8601 format).
4	Invoice Total	The total amount of the invoice including VAT.
5	VAT Total	The total VAT amount charged on the invoice.

Phase 2: The Evolution of the QR Code

In Phase 2 (Integration Phase), the QR code becomes significantly more complex. It is no longer just a summary of the invoice; it becomes a tool for verifying the integrity of the digital document.

In addition to the five basic tags, Phase 2 QR codes for Simplified Tax Invoices (B2C) must include:

• Tag 6 (Invoice Hash): A SHA-256 hash of the invoice XML.
• Tag 7 (Digital Signature): An ECDSA digital signature generated using the private key associated with your Cryptographic Stamp.
• Tag 8 (Public Key): The ECDSA public key used to verify the signature.
• Tag 9 (Certificate Signature): For simplified invoices, the signature of the certificate itself.

💡 Note: For Standard Tax Invoices (B2B), the QR code is generated by the ZATCA portal after the invoice is cleared, whereas for Simplified Invoices, your accounting software must generate it locally.

How to Encode the QR Code: Step-by-Step

To generate a valid ZATCA QR code, your system must follow these steps:

1. Collect Data: Gather all required fields (Seller Name, VAT, etc.).
2. Convert to Hexadecimal TLV: Each field is converted into its TLV hex representation.
   • Example: Tag 1 (Seller Name) with value “ABC” would be 01 (Tag) 03 (Length) 414243 (Value in Hex).
3. Concatenate: Combine all hex strings into one long string.
4. Base64 Encoding: Convert the final concatenated hex string into a Base64 string.
5. Generate Image: Use the Base64 string to generate the QR code image on the invoice PDF.

⚠️ Warning: Simply putting a URL or plain text into the QR code will result in a compliance failure. Use our ZATCA QR Decoder to verify your existing codes.

Common QR Code Errors and How to Fix Them

If you are integrating your system with the Fatoora portal, you might encounter these errors:

• BR-KSA-26: The QR code field does not match the TLV encoding standards.
• BR-KSA-27: The QR code is missing mandatory fields (like the VAT number or timestamp).
• Invalid Timestamp: The timestamp in the QR code must match the IssueDate and IssueTime in the XML exactly.

To ensure your system is ready, you can use the ZATCA Readiness Checker to audit your current setup.

Technical Implementation Example (XML)

Within the ZATCA XML (UBL 2.1), the QR code is stored in the cac:AdditionalDocumentReference section or specifically within the cbc:EmbeddedDocumentBinaryObject under the specific URI for the QR code.

<cac:AdditionalDocumentReference>
    <cbc:ID>QR</cbc:ID>
    <cac:Attachment>
        <cbc:EmbeddedDocumentBinaryObject mimeCode="text/plain">[Base64_Encoded_TLV_Data]</cbc:EmbeddedDocumentBinaryObject>
    </cac:Attachment>
</cac:AdditionalDocumentReference>

Why Manual Implementation is Risky

Attempting to build a TLV encoder and manage cryptographic stamps manually is highly complex and prone to errors. ZATCA regulations change, and Phase 2 requires maintaining a PIH (Previous Invoice Hash) and an ICV (Invoice Counter Value) to ensure the sequence of invoices is never broken.

Using a certified solution like Qeemah ensures that:

• QR codes are automatically generated using the latest ZATCA standards.
• TLV encoding and Base64 conversion are handled instantly.
• Phase 2 cryptographic signatures are applied without manual intervention.

How Qeemah Helps with ZATCA Compliance

Qeemah is designed specifically for the Saudi market, ensuring that every invoice you issue—whether B2B or B2C—is 100% compliant with ZATCA’s technical specifications.

✅ Automated QR Generation: Our Sales & CRM module generates compliant QR codes for every quotation and invoice. ✅ Phase 2 Ready: We handle the integration with the Fatoora portal, including XML generation, hashing, and digital signatures. ✅ Real-time Validation: Our system checks for errors before you send the invoice, preventing ZATCA rejections. ✅ Comprehensive Accounting: Beyond invoicing, manage your Chart of Accounts and Inventory in one cloud-based platform.

Ready to simplify your e-invoicing? View our pricing or contact our experts today for a demo.