The e-invoice QR code
A square code printed on the invoice that carries its key data and stamp as base64-encoded TLV, so a buyer can check it with a phone.
Since phase 1 (4 December 2021) a simplified invoice has had to carry a five-tag QR code: seller name, VAT number, time stamp, total with VAT and VAT total. Phase 2 made the code mandatory on every document and added four tags: the document hash, its signature, the public key and, on simplified documents, ZATCA's signature on the device certificate.
Each tag is three adjacent parts: one byte for the tag number, one byte for the value length, then the UTF-8 value. The tags are concatenated into one byte sequence, base64-encoded, and the image is drawn from that text. The Security standard caps the text at 700 characters.
On a simplified document the seller's device builds the whole code, since it does the stamping. On a standard document the FATOORA platform adds or updates the code at clearance. The QR block in the XML is excluded from the hash, since it contains it.
ZATCA's documents differ on one point worth knowing: the Security standard describes tag 6 as 32 bytes (a binary hash), while the technical guidelines' worked example puts base64 text in tags 6 and 7 (44 characters for the hash). ZATCA's examples also end the time stamp with Z, although the standard allows local time without it.
In JooDax
BuiltThe till prints a nine-tag code on every simplified document, with tags 6 and 7 as base64 text as in the technical guidelines' example. Books' A4 invoices print the five-tag phase-1 code, unsigned. The programs refuse any tag over 255 bytes but do not check the 700-character limit.
crates/jdx-einvoice-sa/src/xml.rs
Steps
- Gather the values: name, VAT number, time stamp, total, VAT, then in phase 2 the hash, signature, public key and ZATCA's signature.
- For each value write the tag byte, then a length byte (the UTF-8 byte count), then the value.
- Concatenate the tags with no separators and base64-encode the whole sequence.
- Put the text in the QR element of the XML and draw the image from it on the printed copy.
The QR code’s tags
| Tag | Name | Phase | Meaning |
|---|---|---|---|
| 1 | Seller's name | 1 | The seller's registered name in UTF-8, as in the seller name field (BT-27). |
| 2 | VAT registration number of the seller | 1 | The seller's 15-digit VAT number (BT-31). |
| 3 | Time stamp of the invoice (date and time) | 1 | Issue date and time in ISO 8601; the Security standard's example is 2022-02-21T12:13:57Z. In phase 2 the programs write local time without Z, mirroring the date and time fields; their phase-1 code uses UTC with Z. |
| 4 | Invoice total (with VAT) | 1 | The total including VAT (BT-112) as numeric text. |
| 5 | VAT total | 1 | The VAT total; version 1.2 of the Security standard clarified that it is the value of BT-110. |
| 6 | Hash of XML invoice | 2 | The document hash. The Security standard gives its length as 32 bytes, while the technical guidelines' worked example carries the 44-character base64 text, as the programs do. |
| 7 | ECDSA signature of the XML hash | 2 | The ECDSA signature of the document hash: made by the seller's device for simplified documents and by ZATCA's platform for standard ones. The programs write it as base64 text, as in the technical guidelines' example. |
| 8 | ECDSA public key | 2 | The public key matching the signing key. The programs write the full DER SubjectPublicKeyInfo (88 bytes for secp256k1), as in the technical guidelines' example. |
| 9 | ECDSA signature of the cryptographic stamp's public key by ZATCA's technical CA | 2 | Simplified documents and their notes only: the signature of ZATCA's certificate authority on the device certificate, copied from the certificate. In local test mode it is a self-signature, not ZATCA's. |
Questions and answers
Why does ZATCA's app show the Arabic name garbled?
Usually because the name was not UTF-8 encoded, or the length counted letters instead of bytes; an Arabic letter is two bytes.
Is the phase-1 code enough after joining phase 2?
No. After integration the document must carry the phase-2 tags; tag 9 applies to simplified documents and their notes only.
Related pages
- KSA-14 QR code
- BT-27 Seller name
- BT-31 Seller VAT registration number
- BT-112 Invoice total amount with VAT
- BT-110 Invoice total VAT amount
- BR-KSA-27 · The document must contain a QR code encoded as base64Binary.
Related concepts
- The cryptographic stamp (digital signature)An ECDSA signature in XAdES form over the document hash and signing properties, made with a registered device key and a ZATCA-issued certificate.
- The invoice hash: how it is computedA SHA-256 fingerprint of the document after removing the stamp and QR blocks and canonicalizing it, written in base64; the stamp and the chain rest on it.
- Phase 1 (generation) and phase 2 (integration)Phase 1, since 4 December 2021, requires issuing and keeping invoices electronically; phase 2, from 1 January 2023 in waves, adds XML, stamping and integration with FATOORA.
E-invoicing in Saudi Arabia (FATOORA)
Sources
- Security Features Implementation Standards to the E-Invoicing resolution dated 2023-05-19 (v1.2) — ZATCA
- E-invoicing Detailed Technical Guidelines (vVersion 2) — ZATCA
- الضوابط والمتطلبات والمواصفات الفنية والقواعد الإجرائية اللازمة لتنفيذ أحكام لائحة الفوترة الإلكترونية (قرار المحافظ رقم 62738 وتاريخ 1443/11/23هـ) (vfile dated 20230519 (decision 62738)) — ZATCA
- Electronic Invoice XML Implementation Standard to the E-Invoicing resolution dated 2023-05-19 (v1.2) — ZATCA
Checked on: 4 November 2026. What concerns JooDax is taken from the programs’ own code.