ZATCA Phase 2 (Integration): The Definitive Technical Guide

There is a particular way that ZATCA Phase 2 guides fail. The narrative is usually fine — clearance for B2B, reporting for B2C, sign the XML, chain the hashes. Then you reach the part you actually needed, the part you were going to paste into a ticket or a config file, and it is quietly wrong. A rule number that belongs to a different rule. An endpoint that has never existed. A specification name that ZATCA has never published. The prose was right and the specifics were invented, which is the worst possible combination, because the specifics are the only reason anyone reads a technical guide.

This guide is written the other way round. Every rule identifier, every endpoint, every field code below is quoted from a document published by ZATCA, and the document is named next to it. Where ZATCA's standard does not say something, this guide says so instead of filling the gap. The sources used are:

• ZATCA, Electronic Invoice XML Implementation Standard, Version 1.2 (dated 2023-05-19) — PDF
• ZATCA, E-invoicing Detailed Technical Guidelines, Version 2 — PDF
• ZATCA, Detailed Guidelines for E-Invoicing, Version 2 — PDF
• ZATCA, Developer Portal User Manual, Version 3 — PDF
• KSA VAT Implementing Regulations (Eighth Edition) — PDF

Phase 1 and Phase 2 are different problems

Phase 1 (Generation), live since 4 December 2021, asked a modest question: can your system produce a structured electronic invoice with a QR code and stop producing handwritten ones? Most businesses answered it by upgrading their POS or accounting software and moving on.

Phase 2 (Integration) asks a different question: can your system talk to ZATCA's. It is enforceable from 1 January 2023 and is being rolled out in waves by taxpayer group. On timing, the Detailed Guidelines are explicit and consistent across three separate passages: "Notifications to the target groups will be initiated at least six months in advance," and "ZATCA will notify taxpayers of their Phase 2 wave at least six months in advance through Official emails & SMS registered with ZATCA."

Six months. Not four, not three. If you have received the notice, you have a real project with a real deadline. If you have not, your wave has not been called yet — but the criteria are set by ZATCA and the waves have consistently reached further down the revenue ladder, so the correct posture is to be ready before the email arrives, not after.

Clearance vs. reporting: one fork, two different systems

This is the single most consequential architectural decision in Phase 2, and it is not a preference. It is determined by the document type.

Source: ZATCA E-invoicing Detailed Technical Guidelines v2, sections on the Reporting and Clearance processes.

Two consequences engineers routinely miss.

First, clearance is synchronous and in the critical path of your sales process. A B2B invoice that has not been cleared is not a tax invoice. If ZATCA's platform is unreachable, you cannot hand the customer a valid document. Your architecture needs a queue, a retry policy, and a human-visible failure state — not a silent catch.

Second, ZATCA can turn clearance off. The Technical Guidelines note: "If ZATCA has disabled the Clearance functionality, even Standard documents (B2B) can be submitted using the Reporting API. In such cases, ZATCA's Platform does not stamp Standard documents (B2B)." The FAQ adds that in that situation a document submitted to the Clearance API "will return a 303 re-[direct]" and must be resubmitted to the Reporting API. If your integration treats a 303 as a fatal error, it will break on the day ZATCA exercises that switch. Handle it.

The document: UBL 2.1, and the two type codes people confuse

Phase 2 invoices are UBL 2.1 XML. The XML Implementation Standard requires that "Tag names and attributes must be correctly written and follow the UBL 2.1 sequence" and that "All UBL 2.1 mandatory elements must be present."

Three header fields cause most of the confusion:

• cbc:ProfileID (BT-23) — rule BR-KSA-EN16931-01: Business process "must be reporting:1.0". It is a fixed string. It does not vary by document type, and it does not become clearance:1.0 for B2B. There is no such value in the standard.
• cbc:InvoiceTypeCode (BT-3) — the document type: 388 invoice, 383 debit note, 381 credit note. Rule BR-KSA-17 requires that a debit or credit note ("invoice type code (BT-3) is equal to 383 or 381") "must contain the reason (KSA-10) for this invoice type issuing."
• cbc:InvoiceTypeCode/@name (KSA-2) — the transaction type. This is the seven-character string that everyone gets wrong, and it is the subject of the next section.

BT-3 and KSA-2 live on the same XML element. One is the element's value, the other is its @name attribute. They answer different questions and they are not interchangeable.

Decoding KSA-2: the NNPNESB structure

Rule BR-KSA-06 of the XML Implementation Standard states, verbatim, that "The invoice transaction code (KSA-2) must exist and respect the following structure: NNPNESB", where:

Source: XML Implementation Standard v1.2, rule BR-KSA-06, applying to /ubl:Invoice/cbc:InvoiceTypeCode/@name.

Worked examples, decoded strictly from that table:

The 0211000 myth, and why it refutes itself

A value of 0211000 circulates widely as "the self-billing code." Decode it against BR-KSA-06 and it says the opposite of what it claims:

• positions 1–2 = 02 → simplified invoice
• position 3 = 1 → third party
• position 4 = 1 → nominal
• positions 5, 6 = 0
• position 7 = 0 → self-billed: FALSE

The code that is supposed to mean "self-billed" has the self-billed flag switched off. It also sets the subtype to simplified, which — as the next section shows — is independently invalid for self-billing. If you have 0211000 in a codebase, it is not a self-billing invoice; it is a nominal, third-party, simplified invoice, and it will not do what you think.

The correct value for a self-billed standard tax invoice is 0100001.

Self-billing, done correctly

Self-billing is where the most damage gets done, because it is the one area where a technical mistake is also a legal one. Three requirements, from three different documents, all of which must hold.

1. ZATCA's prior approval is a legal precondition. VAT Implementing Regulations, Article Fifty-Three (Tax Invoices), paragraph 2:

"Subject to the Authority's approval, a Taxable Customer may issue Tax Invoices on behalf of a Supply made by a Taxable Supplier provided that a prior agreement between such Supplier and Customer has been made to this effect; that the Tax Invoice state that it was issued by the Customer on behalf of the Supplier; and that the Supplier and Customer are registered with the Authority for VAT purposes. A Tax Invoice issued as per this Paragraph will be deemed to be issued by the Supplier. The agreement referred to in this Paragraph must include a recitation of the procedures required for the Tax Invoices to be approved by the Supplier on whose behalf they are issued and a certification by the Supplier that they will not issue invoices in respect of the Supplies for those Tax Invoices were issued."

Read that carefully, because it contains four obligations, not one: the Authority must approve; a prior agreement must exist; the invoice must state on its face that it was issued by the customer on behalf of the supplier; and both parties must be VAT-registered. The agreement itself must additionally spell out the supplier's approval procedure and carry the supplier's certification that it will not also invoice the same supplies.

ZATCA's Detailed Technical Guidelines say the same thing in operational language: "Standard documents (B2B) under Self-Billing are submitted by the Buyer. It is mandatory for the Seller and Buyer to be in a Self-Billing agreement which has been approved by ZATCA."

You cannot switch on self-billing because your ERP has a checkbox for it. Turning that flag on without the Authority's approval is a VAT exposure, not a configuration choice. (The same Article Fifty-Three, paragraph 3, applies an identical "Subject to the Authority's approval" condition to invoices issued through a third party — which is position 3 of KSA-2. Same discipline applies.)

2. Self-billing is B2B only. The XML Implementation Standard's own description of the invoice indicators is unambiguous: "Self Billed — The invoice is issued by the buyer instead of the supplier. It is only applicable in B2B scenarios. It will not have any effect on the fields, however its mandated that the invoice states that it is self-billed."

This is enforced structurally, not just stated. Rule BR-KSA-31 provides that for simplified tax invoices and their notes ("KSA-2, position 1 and 2 = 02"), "only the following are accepted: third party (KSA-2, position 3 = 1), nominal supply (KSA-2, position 4 = 1) and summary transactions (KSA-2, position 6 = 1)." Position 7 is not on that list. A self-billed flag can therefore never legitimately sit on an 02 document — the standard has no path for it.

3. Self-billing cannot be combined with export. Rule BR-KSA-07: "Self-billing is not allowed (KSA-2, position 7 cannot be '1') for export invoices (KSA-2, position 5 = 1)." So 0100101 is invalid by construction.

Everything above is regulatory reality that your systems have to live inside. Where infrastructure comes in is quieter but not smaller: Article Sixty-Six of the VAT Implementing Regulations requires those invoices and records to be kept for a minimum of six years and to be kept in the Kingdom. If you are choosing where the system that generates and stores them will run, that is a decision worth making deliberately. Skyline Cloud runs on Saudi infrastructure with SAR billing and Arabic support — start your free 14-day trial — no credit card and see what your stack looks like when the data never leaves the country.

Cryptographic stamp, hash chain, ICV and QR

The stamp

The Detailed Technical Guidelines specify ECDSA over the secp256k1 curve with SHA-256 hashing. The guidelines' own worked example uses openssl ecparam -name secp256k1 -genkey to produce the private key and openssl req -new -sha256 -key privateKey.pem to produce the CSR. Rule BR-KSA-60 requires the cryptographic stamp (KSA-15) to exist in simplified tax invoices and their associated credit and debit notes. Rule BR-KSA-28 requires that where the stamp exists, it "must contain the exact urn:oasis:names:specification:ubl:signature:1 value for signature information ID."

The asymmetry is worth stating plainly: for simplified invoices you stamp the document, because ZATCA never sees it before the customer does. For standard invoices, ZATCA applies its own stamp during clearance. The Technical Guidelines note the seller "may optionally include its Cryptographic Stamp and QR code as part of the submission" of a standard document, in which case ZATCA "will add an additional Stamp to the document and update the QR code."

PIH — the previous invoice hash

Rule BR-KSA-61: "Previous invoice hash (KSA-13) must exist in an invoice." Rule BR-KSA-26: "If the invoice contains the previous invoice hash (KSA-13), this hash must be base64 encoded SHA256."

Note precisely what BR-KSA-26 is: a format rule. It says the PIH must be a base64-encoded SHA-256 value. It is not a rule that says "your hash chain does not match ZATCA's records." The chain-integrity semantics live in ZATCA's FAQ guidance, and they contain the single most-missed rule in Phase 2:

"in the example above Document 3 should have its Previous Invoice Hash as the hash of Document 2 even though it was rejected."

The chain includes rejected documents. If ZATCA rejects document 2, document 3's PIH is still the hash of document 2. Implementations that "roll back" the chain on rejection — reusing document 2's PIH for document 3 — desynchronise from ZATCA and corrupt every subsequent document. This is the bug that turns a bad afternoon into a bad quarter.

ICV — the invoice counter value

Rule BR-KSA-33: "Each invoice must have an invoice counter value (KSA-16)." Rule BR-KSA-34: "The invoice counter value (KSA-16) contains only digits."

An honesty note: the XML Implementation Standard's BR-KSA rules for the ICV state that it must exist and must contain only digits. They do not, in the text I have, state a numeric increment rule as a validation rule. What ZATCA does state, in the Technical Guidelines FAQ, is the uniqueness and immutability semantics:

"Invoice counter value should not be re-used. Once a document is generated with an Invoice Counter Value (ICV), then that ICV cannot be mentioned on another document. A new document should have its own ICV."

and

"every document shall have its own hash and counter value. Rejected document's hash and counter value should not be changed or updated."

So: never reuse an ICV, never rewrite the ICV of a rejected document, and give every new document a fresh one. Anyone quoting you a BR-KSA rule number for "ICV is not monotonically increasing" should be asked which document it is in.

The rejection asymmetry nobody documents

This is subtle and it is in ZATCA's FAQ, and the two halves differ:

• Reporting (simplified) rejection: the corrected invoice "should include its own new unique hash, UUID, invoice counter value and timestamp. The date on invoice should remain as when transaction took place."
• Clearance (standard) rejection: the corrected invoice "should include its own new unique hash, UUID, invoice counter value and timestamp. The date on invoice should be updated as non-cleared invoice is not considered as a valid Tax Invoice from ZATCA's perspective."

Same failure, opposite handling of the invoice date. If your remediation path treats both the same way, one of them is wrong.

QR code

Mandatory, Base64-encoded, up to 700 characters, encoded in Tag-Length-Value (TLV) — tag in one byte, length of the UTF-8 byte array in one byte, then the UTF-8 value. The fields and their tags, from the Detailed Technical Guidelines section 6:

Rule BR-KSA-27 requires the document to "contain a QR code (KSA-14), and this code must be base64Binary."

CSID onboarding: the real endpoints

These are the API paths as published by ZATCA in the Developer Portal User Manual, Version 3. Each one below is quoted from that manual, with the page it appears on. ZATCA publishes the environment base URLs (sandbox / simulation / production) in the Developer Portal itself; the paths are what matter here, and this guide does not assert a base host it has not verified.

Note what is not in that table: there is no /compliance/csids, and there is no /renew. Renewal is a PATCH on the same /production/csids path that issues the certificate. If your integration is calling a /renew endpoint, it is calling something ZATCA does not publish.

Headers and bodies, as documented

• Accept-Version — required. The manual states: "V2 refers to the Version of the APIs used and should be mentioned in the API calls (V2 is currently the only valid version)."
• OTP — required header on the Compliance CSID call and on the Production CSID (Renewal) call. The manual describes it as a "One time password generated from Fatoora portal."
• Accept-Language — "Currently supported languages are English (en) and Arabic (ar) and it defaults to English."
• Authorization — Basic. For production calls the manual is explicit: "run the Compliance CSID API to obtain the 'binarySecurityToken' to be used as the Username and 'secret' as the Password."

Request bodies, from the manual's own examples:

• POST /compliance → { "csr": "<base64 CSR>" }
• POST /production/csids → { "compliance_request_id": "1234567890123" }
• POST /invoices/reporting/single → "The body object should Contain 2 Values: the first one is called invoiceHash and the second one is called invoice."

A successful reporting call returns HTTP 200 with an object containing invoiceHash, status (e.g. "Reported"), warnings and errors.

The onboarding sequence

1. Generate a keypair and a CSR meeting ZATCA's CSR specification (secp256k1).
2. Obtain an OTP from the Fatoora portal.
3. POST /compliance with the CSR and the OTP header → receive the Compliance CSID (CCSID) and a compliance_request_id.
4. Run the compliance checks via POST /compliance/invoices, authenticated with the CCSID. The manual is clear that these checks are a prerequisite: the Production CSID request "will return an invalid response until these" compliance checks are completed.
5. POST /production/csids with the compliance_request_id → receive the Production CSID (PCSID).
6. Use the PCSID to authenticate clearance and reporting calls.
7. Renew with PATCH /production/csids (OTP header required) before expiry.

Validation rules you can actually cite

ZATCA's platform returns rule identifiers of the form BR-KSA-nn (KSA-specific rules) and BR-KSA-EN16931-nn (KSA overrides of the EN 16931 rule set). The Developer Portal Manual confirms the precedence: the Clearance API validates against "1. Compliance to the UBL2 XSD. 2. EN 16931 Rules subset. 3. KSA Specific Rules set. KSA Rules set will override EN 16931 Rules set in case the same rule exists in both sets."

Every rule in this table is quoted from the XML Implementation Standard v1.2. Nothing has been paraphrased into a different meaning:

Take BR-KSA-15 seriously as a case study. It is about the supply date. It is not, and has never been, a rule about the invoice counter. If a guide, a vendor, or a support ticket tells you BR-KSA-15 means "ICV is not monotonic," that guide is not reading the standard — and everything else it tells you should be treated with the same suspicion.

Things that do not exist

Stated plainly, because these appear in circulating guides and cost real engineering hours:

• PINT-KSA. The string "PINT" appears zero times in ZATCA's XML Implementation Standard, in the Detailed Technical Guidelines, and in the Detailed Guidelines for E-Invoicing. PINT is a Peppol construct. ZATCA has not adopted it. There is no "PINT-KSA" specification to comply with.
• Error codes of the form ZATCA-INV-nnn or ZATCA-CRT-nnn. Zero occurrences across all three ZATCA documents. ZATCA's validation identifiers are BR-*, BR-KSA-* and BR-KSA-EN16931-*.
• A /compliance/csids endpoint or a /renew endpoint. Not in the Developer Portal Manual. See the endpoint table above.
• clearance:1.0 as a ProfileID. BR-KSA-EN16931-01 fixes BT-23 at reporting:1.0 regardless of document type.

Retention and residency: the part that outlives the integration

Once the integration works, the obligation does not end — it becomes a storage problem. Article Sixty-Six of the VAT Implementing Regulations is short and load-bearing:

• 66(1): "The invoices, books, records and accounting documents required to be maintained by a Taxable Person ... shall be kept for a minimum period of six (6) years from the end of the Tax Period to which they relate."
• 66(2): "Records shall be kept in Arabic, and all Tax Invoices shall be issued in Arabic in addition to any other language also shown on the Tax Invoices as a translation."
• 66(3): "...invoices, records and documents shall be kept in the Kingdom either physically or electronically through access to the relevant server or databases where on which they are stored via a terminal point or access point in the Kingdom."

Be precise about 66(3), because it is often overstated. It does not say, in these words, that the server must be physically inside Saudi Arabia in every case — it contemplates electronic keeping "through access to the relevant server or databases ... via a terminal point or access point in the Kingdom," and it applies "without prejudice to any law, regulations or instructions applicable in the Kingdom relating to keeping and maintaining records and documents, electronic transactions, or cyber security." Other regimes — PDPL, and NCA controls for regulated sectors — may bind you harder than Article 66 does on their own.

What is not ambiguous: you owe six years of retrievable, Arabic, tamper-resistant records, and ZATCA can ask for them. Article 66(3)(f) requires the taxable person to "take the necessary security measures and adequate controls that can be reviewed and examined to prevent tampering with invoices, documents, and electronic records."

The simplest way to satisfy an in-Kingdom record-keeping obligation is to keep the records in the Kingdom. If the system that generates or archives your e-invoices currently runs on infrastructure in Frankfurt or Virginia, that is a question you will be asked eventually — by an auditor, a customer's procurement team, or your own board. Skyline Cloud is Saudi-hosted, billed in SAR, supported in Arabic, with daily backups and free auto-renewing SSL on every plan. Start your free 14-day trial — no credit card required.

To be equally plain about what we are not: Skyline is a managed cloud hosting and business cloud services provider. We host the systems and the records. We do not sell a ZATCA clearance integration, and this guide is not a substitute for your own reading of the standard or for professional tax advice.

FAQ

Is Phase 2 mandatory for my company? Phase 2 applies to persons subject to the E-Invoicing Regulations, rolled out in waves by taxpayer group according to criteria set by ZATCA. ZATCA notifies each target group at least six months in advance by official email and SMS registered with ZATCA. If you are VAT-registered and have not been notified, your wave has not been called — yet.

What is the correct invoice transaction code (KSA-2) for a self-billed invoice? 0100001 — subtype 01 (standard tax invoice) with position 7 (the self-billed flag) set to 1. Per BR-KSA-06. The frequently-circulated 0211000 is wrong: it sets subtype to simplified and leaves the self-billed flag at 0.

Can I issue a self-billed simplified (B2C) invoice? No. The XML Implementation Standard states self-billing "is only applicable in B2B scenarios," and BR-KSA-31 permits only third-party, nominal and summary flags on 02 documents. There is no valid representation of a self-billed simplified invoice.

Do I need ZATCA's permission to self-bill? Yes. VAT Implementing Regulations Article 53(2) makes it "subject to the Authority's approval," requires a prior written agreement, requires the invoice to state it was issued by the customer on behalf of the supplier, and requires both parties to be VAT-registered. ZATCA's Technical Guidelines repeat that a ZATCA-approved self-billing agreement is mandatory.

What happens to my hash chain when ZATCA rejects a document? The rejected document stays in the chain. ZATCA's guidance: document 3's previous invoice hash is the hash of document 2 "even though it was rejected." The rejected document's hash and counter value "should not be changed or updated," and the replacement document gets a new hash, UUID, ICV and timestamp.

Does the invoice date change when I resubmit after a rejection? It depends on the model, and this trips people up. For reporting (simplified), "the date on invoice should remain as when transaction took place." For clearance (standard), "the date on invoice should be updated," because a non-cleared invoice is not a valid tax invoice from ZATCA's perspective.

Which curve and hash does the cryptographic stamp use? ECDSA on secp256k1, with SHA-256, per the Detailed Technical Guidelines.

Is there a PINT-KSA specification I need to support? No. "PINT" does not appear anywhere in ZATCA's XML Implementation Standard, Detailed Technical Guidelines, or Detailed Guidelines for E-Invoicing.

How long must I keep e-invoices, and where? A minimum of six years from the end of the relevant Tax Period, in Arabic, kept in the Kingdom — VAT Implementing Regulations Article 66(1), 66(2) and 66(3).

Phase 2 rewards the teams who read the actual standard and punishes the ones who read summaries of it. Every number in this guide can be traced back to a ZATCA PDF linked at the top; if you find one that cannot, we want to know.

Whatever generates your invoices, something has to store them — for six years, in Arabic, retrievably, in the Kingdom. If you would rather that "something" be Saudi infrastructure with Arabic support and SAR billing than a region you have to explain to an auditor, start your free 14-day trial at Skyline Cloud — 14 days, no credit card.

Related reading: Saudi PDPL — the practical compliance guide · Saudi Aramco SACS-002: what Aramco actually asks contractors for · Data residency and cloud hosting in Saudi Arabia · Skyline Cloud hosting plans · Skyline Cloud in Riyadh