ZATCA e-invoicing glossary
Every term you meet while connecting to ZATCA's Fatoora platform, with an example and the rule that fails when it is wrong.
- Clearance · Clearance is ZATCA's model for standard (B2B) tax invoices: the invoice goes to ZATCA before the buyer, which validates it, stamps it and sends it back.
- Compliance checks · ZATCA compliance checks are sample documents a device files with its compliance CSID before going live: an invoice, credit note and debit note per invoice type.
- Compliance CSID · The compliance CSID is the first certificate a device gets from ZATCA, in exchange for a CSR and an OTP, used to pass the compliance checks.
- Credit note · A ZATCA credit note (code 381) refunds the buyer or corrects an invoice. It must reference the original invoice and state the reason for issuing it.
- Cryptographic stamp (XAdES / ECDSA) · The ZATCA cryptographic stamp is an XAdES signature over the invoice using ECDSA on secp256k1 with the device's CSID key, proving origin and integrity.
- CSID (Cryptographic Stamp Identifier) · A CSID is the certificate ZATCA issues to one e-invoicing device (EGS) in the taxpayer's name; the device signs invoices and calls the Fatoora API with it.
- CSR (Certificate Signing Request) · A CSR is the request a device sends ZATCA to get a CSID: it holds the secp256k1 public key plus the taxpayer and device fields ZATCA requires.
- Debit note · A ZATCA debit note (code 383) increases the value or VAT of an earlier invoice. It must reference the original invoice and state the reason.
- EGS (E-invoice Generation Solution unit) · An EGS is the unit that issues ZATCA e-invoices: a till, POS or server. Each unit is onboarded on its own and gets its own CSID and invoice chain.
- Fatoora portal · Fatoora is ZATCA's e-invoicing platform: taxpayers generate OTPs there to onboard and renew devices, and it receives invoices through the API.
- ICV (Invoice Counter Value) · ICV is the sequential counter every ZATCA e-invoicing device (EGS) stamps on each invoice and note it issues: it starts at 1 and goes up by one. Rule BR-KSA-33.
- Invoice hash · The ZATCA invoice hash is the base64 SHA-256 of the invoice XML with the signature and QR removed and C14N11 applied. It becomes the next invoice's PIH.
- InvoiceTypeCode · ZATCA InvoiceTypeCode: 388 invoice, 381 credit note, 383 debit note. Its name attribute (0100000 or 0200000) marks a standard or simplified invoice.
- OTP (Fatoora portal one-time password) · The OTP is a one-time code the taxpayer generates in ZATCA's Fatoora portal to approve onboarding a device. It is valid for one hour.
- PDF/A-3 · PDF/A-3 is an archival PDF that can carry attached files. ZATCA accepts it for sharing and storing invoices when the XML is embedded; submission stays XML.
- Phase 1 vs Phase 2 · ZATCA Phase 1 (Generation, from 4 Dec 2021) requires electronic invoices; Phase 2 (Integration, from 1 Jan 2023 in waves) adds signed XML filed with ZATCA.
- PIH (Previous Invoice Hash) · PIH is the hash of the device's previous invoice, written into the next one so a ZATCA device's invoices form a chain. BR-KSA-61 requires it.
- Production CSID · The production CSID is the certificate a ZATCA device signs and files legal invoices with. It is issued after the compliance checks and renewed with a new OTP.
- 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.
- Reporting · Reporting is ZATCA's model for simplified (B2C) invoices: the buyer gets the invoice at once, stamped by your device, and it is reported within 24 hours.
- Simplified tax invoice · A ZATCA simplified tax invoice is the B2C invoice: transaction code starting 02, stamped by the device, carrying a QR code, reported within 24 hours.
- Standard tax invoice · A ZATCA standard tax invoice is the B2B invoice: transaction code starting 01, with buyer details and a supply date, cleared by ZATCA before delivery.
- UBL 2.1 · UBL 2.1 is the XML standard ZATCA Phase 2 invoices are written in, validated with the XSD, the EN 16931 rules and ZATCA's own KSA rules.
- VAT categories (S, Z, E, O) · ZATCA invoices use four VAT category codes: S standard, Z zero-rated, E exempt, O out of scope. Each line has one, each category its own breakdown.
- VATEX exemption reason codes · VATEX codes give the reason for VAT exemption or zero-rating on a ZATCA invoice, e.g. VATEX-SA-32 for exports. A wrong-category code breaks BR-KSA-CL-04.
- ZATCA environments (developer portal, simulation, production) · ZATCA has three environments: developer portal for testing, simulation with real taxpayer data and no legal effect, and production. Each issues its own CSIDs.
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