ZATCA QR code reader

Every simplified tax invoice issued in Saudi Arabia, the receipt a consumer gets, carries a QR code. Scan it with an ordinary phone camera and you get a line of letters and numbers that means nothing on sight. That line is Base64 text, and inside it is a short list of fields describing the invoice. This reader unpacks it and shows you what it says.

How the code is built

ZATCA's format is Tag-Length-Value, usually shortened to TLV. Each field is written as three parts: one byte for the tag number, one byte for the length of the value, then the value itself in UTF-8 text, so Arabic seller names survive intact. The fields are joined end to end and the whole thing is encoded as Base64, which is the text the QR code holds. ZATCA caps that text at 500 characters.

The TLV structure, the Base64 encoding and the list of tags are defined in ZATCA's QR code guide. ZATCA, Guide to Developed FATOORA Compliant QR Code

The five Phase 1 fields

• Tag 1: the seller's name
• Tag 2: the seller's VAT registration number
• Tag 3: the timestamp, the date and time of the invoice
• Tag 4: the invoice total including VAT
• Tag 5: the VAT total

These five became mandatory on 4 December 2021, at the start of the generation phase. Every compliant code has them, and the reader shows each one as text.

Phase 2 fields

From 1 January 2023, invoices issued through the integration phase carry four more tags. Tag 6 is a hash of the XML invoice. Tag 7 is an ECDSA signature. Tag 8 is the ECDSA public key. Tag 9, on simplified invoices and their notes, is ZATCA's signature over the public key of the cryptographic stamp. These are binary values, not text, so the reader reports each by its size and marks the code as Phase 2.

Tags 6 to 9 and their 1 January 2023 date are listed in the same guide. ZATCA QR code guide, tags 6 to 9

What the reader checks

• That the text is valid Base64 and splits cleanly into TLV fields, with no length running past the end
• That the five Phase 1 fields are present
• That the VAT number has the shape a Saudi VAT registration number takes: 15 digits, starting and ending with 3
• That the VAT total divided by the amount before VAT comes to 15 per cent, the standard rate

The rate check works from the code's own figures. Subtract the VAT total from the invoice total to get the amount before VAT, then divide the VAT by that. A result far from 15 per cent can mean a zero-rated line, a mix of rates, or a code built wrongly, and it is worth comparing against the printed invoice.

What it does not prove

A valid-looking code proves only that someone encoded those five values correctly. Anyone can do that, and this site's own invoice builder does it for its Phase 1 codes. The reader does not verify the Phase 2 signature, because that needs ZATCA's certificate chain, and it cannot tell you whether the invoice was ever reported to or cleared by ZATCA. It also cannot confirm that the VAT number belongs to the business named, or is registered at all.

For those questions, use ZATCA's own channels. The reader is for the everyday checks: does the receipt in your hand match the code printed on it, and was your own system's code built the way the guide describes?

Problems it helps you spot

• A code holding a website link or plain text instead of TLV data, which fails to decode
• Totals in the code that differ from the totals printed on the invoice
• The VAT total and the invoice total swapped
• A timestamp with no time, or in a format other than the ISO 8601 style in ZATCA's examples
• Arabic names that were not encoded as UTF-8, which the reader rejects rather than showing garbled

Decoding runs entirely in your browser. The text you paste and any picture you upload stay on your device; nothing is sent to this site or to anyone else.