QR code (TLV)
The ZATCA Phase 2 QR code holds 9 TLV tags encoded in base64: seller name, VAT number, timestamp, totals, invoice hash, signature and public key.
The Phase 2 QR code is not a URL or plain text: it is 9 fields, each written as TLV (tag number, length, value), concatenated and base64-encoded. Tags: 1 seller name, 2 seller VAT number, 3 issue timestamp, 4 total with VAT, 5 VAT total, 6 invoice hash, 7 signature, 8 public key, 9 ZATCA's signature on the certificate.
In the XML it is a cac:AdditionalDocumentReference whose cbc:ID is QR, with the value in cbc:EmbeddedDocumentBinaryObject and mimeCode="text/plain". This element is removed before the invoice hash is computed.
What goes wrong: BR-KSA-27 requires the QR, and in our SDK 3.4.8 tests it is enforced on simplified invoices only. BR-CL-KSA-14 limits it to 1 to 1000 characters. Common build mistakes: tag 4 or 5 not matching PayableAmount and TaxAmount in the XML, a timestamp with a time zone the XML does not have, and seller names over 127 bytes written without a BER long length. On standard invoices ZATCA generates the QR at clearance.
Matheel builds the tags from the same totals as the XML, returns qr for you to print, and draws it on the PDF.
Example
<cbc:ID>QR</cbc:ID> → base64 TLV, decoded:
1 seller name شركة توريد التكنولوجيا بأقصى سرعة المحدودة | Maximum Speed Tech Supply LTD
2 VAT number 399999999900003
3 timestamp 2022-08-17T17:41:08
4 total + VAT 231.15
5 VAT total 30.15
6 invoice hash z5F9qsS6oWyDhehD8u8S0DaxV+2CUiUz9Y+UsR61JgQ=
7 signature MEYCIQ…
8 public key (DER bytes)
9 stamp sig. (DER bytes)
FAQ
How many fields are in a Phase 2 QR code?
Nine TLV tags in base64, per ZATCA's guidelines. Matheel adds tag 9 on simplified invoices.
How do I read a ZATCA QR code?
Base64-decode it, then read each field: one byte of tag, the length, then the value. Or use Matheel's QR decoder.
Related ZATCA rules
Related terms
Let Matheel handle this for you
Matheel signs the invoice, files it with ZATCA and keeps the counter and hash in one request, and returns the PDF with the QR.
Try Matheel, no signup Matheel API docs