Skip to content
barcoder

Standards/zatca-einvoice-qr

ZATCA eInvoice QR

TypeQR Data Format
PrimarySA
Completeness76%high

Overview

The ZATCA e-invoice QR code is the QR Code that Saudi Arabia's Zakat, Tax and Customs Authority requires on e-invoices under its FATOORA programme. The symbol holds a Base64 string, and that string decodes to a binary tag-length-value (TLV) list of invoice fields 1 3.

It comes in two forms. The Phase 1 code carries 5 plain fields: seller name, VAT number, timestamp, total and VAT. The Phase 2 code adds 4 cryptographic fields: invoice hash, ECDSA signature, public key and, on simplified invoices, a signature from ZATCA's technical CA 1 7. It is a tax-verification code, not a payment code: scanning it checks an invoice and cannot pay it 5 29.

History

  • 4 December 2020: ZATCA published the E-Invoicing Regulation, approved by its Board of Directors, and it took effect on publication 17. The text allowed 12 calendar months to implement it, and it names the authority as the General Authority of Zakat and Tax 6.
  • 28 May 2021: version 1.0 of the Security Features Implementation Standards appeared 1.
  • 18 November 2021: ZATCA published its guide to building a compliant code, then capped at 500 characters 3.
  • 4 December 2021: Phase 1 (Generation) became enforceable for all taxpayers except non-residents 12, with the 5-field QR mandatory on simplified invoices 7.
  • 24 June 2022: version 1.1 of the standard added the ordered encoding steps 1. It already allowed 700 characters 2.
  • 1 January 2023: Phase 2 (Integration) began, in waves by taxpayer group 12.
  • 19 May 2023: version 1.2 elaborated the definition of tag 5, the VAT total 1.
  • 24 July 2026: ZATCA set the criteria for Wave 25 13.

Technical specification

Carrier. An ordinary QR Code whose text is Base64, up to 700 characters 1. None of the ZATCA documents read for this page sets a QR version, error-correction level or print size. ZATCA's guide lists four payloads as wrong: a link to a website, a link to the invoice online, plain readable text, and empty or random values 3.

Encoding order 1:

  1. Start with an empty byte array.
  2. For each field, append one tag byte, one length byte (unsigned 8-bit), then the value.
  3. Base64-encode the array.
  4. Make the QR image from the Base64 string.

Text values are UTF-8, and the length counts bytes, not characters. There are no separators or padding between records 1 3. One length byte means no value can exceed 255 bytes. ZATCA describes the scheme as a simple version of ASN.1 Basic Encoding Rules 3.

Tags by phase

Tag Field Phase 1 Phase 2
1 Seller's name Yes Yes
2 Seller's VAT registration number Yes Yes
3 Invoice date and time, ISO 8601 Yes Yes
4 Invoice total with VAT Yes Yes
5 VAT total, the value in business term BT-110 Yes Yes
6 Hash of the XML invoice No Yes
7 ECDSA signature of the XML hash No Yes
8 ECDSA public key No Yes; optional on platform-stamped tax invoices
9 ZATCA technical CA's ECDSA signature No Simplified invoices and their notes only

Sources: 1 7.

Who signs. On simplified invoices the seller's e-invoice generation solution produces the stamp, and tag 8 is that solution's key. On tax invoices integrated with the platform, ZATCA's platform produces the stamp, and tag 8 is the platform's key 7. For simplified documents, the seller must include stamp and QR, and FATOORA does not stamp them. For standard documents the seller may include them, and the platform adds its stamp and updates the QR during clearance 4.

Cryptography. The standard requires SHA-256, ECDSA and a 256-bit key 1. It does not name the curve. ZATCA's technical guideline generates keys with OpenSSL on secp256k1 4, and the third-party Zatca.Net package uses the same curve 22.

The hash. The hash is computed after removing the UBLExtensions block, the AdditionalDocumentReference with ID QR, and the Signature block. The result is canonicalised with C14N11, hashed with SHA-256 and Base64-encoded 9. The QR element is also outside the signed content 1, so the code can be replaced during clearance without breaking the stamp's coverage.

In the XML. The code sits in cac:AdditionalDocumentReference/cac:Attachment/cbc:EmbeddedDocumentBinaryObject. It is field KSA-14, and rule BR-KSA-27 requires it to be base64Binary 9. The technical guideline maps tags 1 to 9 to XML elements, with tag 3 joining IssueDate and IssueTime 4.

Byte formats of tags 6 to 9: the sources disagree

Security standard v1.2 says tag 6 has a length of 32 bytes and holds a byte array 1. ZATCA's technical guideline of November 2022 publishes a full 9-tag sample that does something else 4. Decoding it gave:

Tag Bytes in the sample Form
6 44 Base64 text of the 32-byte hash
7 96 Base64 text of a 71-byte DER signature
8 88 Raw DER public key structure
9 72 Raw DER signature

The whole sample is 388 bytes and 520 Base64 characters. Chilkat's vendor example follows the same mix 21. The Zatca.Net package describes tag 6 as hash bytes and tag 7 as a raw 64-byte r‖s value, the literal reading 22. The guideline's table also misstates several lengths (45, 192, 48 and 144), and tag 5 (114.90) differs from the encoded 144.9, so trust the encoded bytes 4. Implementers should test against ZATCA's SDK.

The definition of tag 9 also varies. The 2021 guide and 2022 guideline call it the CA's signature of the stamp's public key 3 4; the Resolution calls it the signature of the stamp issued by the CA 7. In practice, the guideline tells developers to copy the signature value from the decoded production certificate 4.

Worked Phase 1 sample

ZATCA's guide gives this example; the seller and number are ZATCA's own sample values 3:

AQxCb2JzIFJlY29yZHMCDzMxMDEyMjM5MzUwMDAwMwMUMjAyMi0wNC0yNVQxNTozMDowMFoEBzEwMDAuMDAFBjE1MC4wMA==

It decodes to 70 bytes. Tag 1 is Bobs Records (12 bytes), tag 2 310122393500003 (15), tag 3 2022-04-25T15:30:00Z (20), tag 4 1000.00 (7) and tag 5 150.00 (6).

Use cases

  • Retail receipts. Simplified tax invoices are usually B2C, and the code must be on the printed copy given to the buyer. In Phase 2 they are stamped by the seller and reported to FATOORA within 24 hours 5 10.
  • B2B clearance. Standard tax invoices go to FATOORA first, which validates them, stamps them and returns them with the QR included or updated 4 5.
  • Customer verification. A customer scans with ZATCA's VAT App, which checks the content is compliant and shows the content and result 5. The platform can also take scanned QR codes and the app's offline validation outcomes 4.
  • Credit and debit notes. Annex rules apply to Electronic Notes as well as invoices 7.
  • Non-signing POS terminals. A taxpayer server can stamp and apply the QR on simplified invoices, so the terminal needs no CSID of its own 4.

The Fatoora platform handled more than 8.2 billion e-invoices in 2025, up 64% from more than 5 billion in 2024. Those are ZATCA figures as reported by Al-Eqtisadiah 20.

Implementations

ZATCA's own Compliance and Enablement Toolbox (SDK) is the reference checker. The guide lists fatoorah validateqr -qr to validate QR structure and fatoorah generate -f <invoice>.xml -q to generate a compliant code 3. ZATCA states that passing the SDK does not mean an invoice has been approved 19.

All libraries below are unofficial. Stars and dates come from GitHub's topic listing, read on 2026-10-30 23.

Library Language Stars Last active Role
SallaApp/ZATCA PHP 168 2026-10 Encoder; README claims Phase 1 and 2
axenda/zatca TypeScript 60 2023-07 Encoder; validated against the SDK as of 18 November 2021
TheAwiteb/fatoora Python 33 2022-11 Encoder and image reader for tags 1 to 5; archived
Haraj-backend/zatca-sdk-go Go 20 2021-12 EncodeTLV and DecodeTLV; no image output

The three smaller projects were last active between 2021 and 2023, so check them before using them for Phase 2 invoices.

Comparison

  • EMVCo MPM also uses TLV in a QR, but as readable text: a 2-digit ID, a 2-digit length and a CRC-16 checksum 28. ZATCA's TLV has binary tags and lengths, then Base64, and has no checksum field. Phase 2 uses signatures for integrity instead. Choose by purpose: EMV QR starts a payment, while the ZATCA code proves an invoice.
  • Oman's Fawtara QR, per vendor Fonoa, is expected to hold seller name, VAT number, timestamp, total, VAT and a Seller UUID, with no authority-applied stamp 30. This comes from a third party only.

Other tax QR pages: Portugal ATCUD QR, India GST eInvoice QR, TicketBAI QR, Spain VeriFactu QR, Poland KSeF QR.

Fun facts

  • ZATCA's guide tells developers to use UTF-8 for Arabic, but its Arabic hex sample is not UTF-8. The string 62764462c648… is the Unicode code points of "الجواهري العربي" run together, with leading zeros dropped. The real UTF-8 is 29 bytes, starting d8a7d984 3.
  • The same guide's JavaScript snippet sets the length from tagValue.length, which is 15 for that name instead of 29 bytes. Its Dart snippet correctly measures the encoded bytes 3.

Status

Active and mandatory. The legal basis is the E-Invoicing Regulation of 4 December 2020, which covers resident taxable persons and those issuing tax invoices on their behalf; non-residents are excluded 6. The detail is in the Controls, Requirements, Technical Specifications and Procedural Rules. The 2023 text cites Governor's Decision No. (62738) dated 23/11/1443 H, and ZATCA published this updated version on 19 May 2023 7 17. The Arabic version prevails over the English translation 7.

Who needs which code:

  • Phase 1: the QR is mandatory on simplified invoices and notes 7 8. For tax invoices, ZATCA's FAQ and Phase 1 page call it optional, and its guideline says not mandated 10 11 5. The security standard's opening line says it is mandatory "for Electronic Tax Invoices" without separating the phases 1.
  • Phase 2: the QR is mandatory for all types of electronic invoices and notes, once a taxpayer's target group is due 7.

Wave status. The latest wave is Wave 25, for taxpayers with VAT-subject revenue above SAR 187,500 in 2022, 2023, 2024 or 2025, who must integrate by 1 February 2027 13. It follows Wave 24, above SAR 375,000, due by 30 June 2026 14. EY reports Wave 25 as ZATCA Governor Decision No. (1448-99-238), which we could confirm only from EY 15; KPMG reports the same threshold and date 16. ZATCA gives each wave at least 6 months' notice 13. No later wave had been found as of 30 October 2026.

ZATCA's security page, updated 10 August 2026, still lists the 19 May 2023 standard 18.

Sources

  1. Security Features Implementation Standards, version 1.2 — ZATCA, 2023
  2. Security Features Implementation Standards, version 1.1 — ZATCA, 2022
  3. Guide to Developed FATOORA Compliant QR Code — ZATCA, 2021
  4. E-invoicing Detailed Technical Guidelines, version 2 — ZATCA, 2022
  5. Detailed Guidelines for E-Invoicing, version 2 — ZATCA, 2023
  6. E-invoicing Regulation — ZATCA, 2020
  7. Controls, Requirements, Technical Specifications and Procedural Rules (2023 text) — ZATCA, 2023
  8. Controls, Requirements, Technical Specifications and Procedural Rules (2021 text) — ZATCA, 2021
  9. Electronic Invoice XML Implementation Standard, version 1.2 — ZATCA, 2023
  10. Frequently Asked Questions: E-invoicing (FATOORA) — ZATCA, 2021
  11. How to Prepare? (Phase 1) — ZATCA, accessed 2026
  12. Roll-out phases — ZATCA, updated 1 September 2026
  13. ZATCA Determines the Criteria for Selecting the Targeted Taxpayers in Wave 25 — ZATCA, 24 July 2026
  14. Criteria set for taxpayers in Wave 24 of E-invoicing — ZATCA, 26 September 2025
  15. Saudi Arabia announces 25th wave of Phase 2 e-invoicing integration — EY, 10 August 2026
  16. Saudi Arabia: e-invoicing mandatory for taxpayers with revenue above SAR 187,500 — KPMG, 29 July 2026
  17. Laws and Regulations — ZATCA, accessed 2026
  18. Security requirements — ZATCA, updated 10 August 2026
  19. Download SDK — ZATCA, accessed 2026
  20. Fatoorah platform e-invoice figures — Al-Eqtisadiah via Arab News PK, 7 January 2026
  21. ZATCA QR code ECDSA signing — Chilkat (vendor), accessed 2026
  22. Zatca.Net package — NuGet (third party), accessed 2026
  23. zatca topic — GitHub, accessed 2026-10-30
  24. axenda/zatca — GitHub, accessed 2026
  25. Haraj-backend/zatca-sdk-go — GitHub, accessed 2026
  26. TheAwiteb/fatoora — GitHub, accessed 2026
  27. SallaApp/ZATCA — GitHub, accessed 2026
  28. EMVCo Merchant-Presented Mode — Barcoder research report
  29. Saudi Arabia payments report — Barcoder research report
  30. E-invoicing in Oman — Fonoa (vendor), updated 10 August 2026

Deployments

No country reports mention this standard by name.

source · content/standards/zatca-einvoice-qr/index.md