Why Is My ZATCA Phase 2 Invoice Being Rejected? is the most frequently asked question nowadays

And the direct answer is that ZATCA Phase 2 rejections are rarely accounting errors. They are technical integration failures. The most common causes are broken ICV sequences, expired CSID certificates, malformed TLV QR codes, and incorrect XML schema structures, all of which can be resolved systematically once you understand what triggers them.

This guide gives you the exact diagnostic framework and operational fixes that Saudi finance teams need right now. By the end, you will know:

• The 8 most documented ZATCA API error codes, what triggers each one, and the precise steps to resolve them without disrupting your invoice flow.
• When real-time clearance is legally required vs. when the 24-hour reporting window applies, and the serious compliance risk of confusing the two.
• How to correctly link Credit and Debit Notes to their original invoice UUID — the single field responsible for over 70% of note rejections.
• Why your PDF is not your legal invoice and what PDF/A-3b with embedded XML means for your audit exposure.

The Integration Phase: Technical Compliance Is the New Battleground

On January 1, 2023, Saudi Arabia entered a landmark phase of digital fiscal transformation. ZATCA — the Zakat, Tax and Customs Authority — launched Phase 2 of the e-invoicing mandate, officially designated as the Integration Phase. Unlike Phase 1, which simply required businesses to issue structured digital invoices, Phase 2 demands a live, continuous technical connection between each company's invoicing system and the ZATCA Fatoora Portal, with every invoice cryptographically validated in real time or within a strict 24-hour window.

Businesses are onboarded through consecutive activation waves — ZATCA assigns each company a mandatory go-live date — and from the moment a business enters its wave, every invoice it issues must pass a multi-layer technical validation before it is considered legally valid. An invoice that fails to clear or is not reported within the required window is not merely incomplete — it is legally void, exposing the company to explicit financial penalties and intensive tax audits.

To understand the true scope of this challenge, consider that Phase 2 requires every entity to: obtain a unique CSID (Cryptographic Stamp Identifier) certificate for each E-Invoicing Generation Solution (EGS) device; generate an RFC 4122-compliant UUID for every single invoice; embed a TLV-encoded QR code in every simplified invoice; maintain an unbroken sequential invoice counter chain across all document types; and archive every document in PDF/A-3b format with a validated XML file embedded inside.

This guide is designed as your primary operational reference when you encounter a rejection from the Fatoora Portal API or when you need a deep understanding of integration requirements before your activation wave arrives. We will walk through the most documented technical errors, the correct workflows, and how Wafeq E-invoicing manages all these complexities automatically — with zero manual intervention from your finance team.

Why Do Businesses Struggle in Phase 2 Despite Having a Good Accounting System?

The short answer: because Phase 2 is not an accounting test — it is a technical engineering test. The challenge is not whether a company can issue a mathematically correct invoice; the challenge is whether its technical system can communicate with ZATCA's digital infrastructure to the precise specifications required. Companies relying on legacy accounting software or generic ERP systems that have not been specifically configured for ZATCA Phase 2 find themselves receiving API rejections even when their accounting data is perfectly accurate.

The following are the most commonly observed root causes of ZATCA rejections, identified by Wafeq through direct work with hundreds of Saudi businesses across multiple activation waves:

• No centralized system to manage UUIDs and track the sequential Invoice Counter Value (ICV)
• CSID certificate expiry with no automated renewal alerts or monitoring in place.
• Incomplete QR/TLV encoding with one or more of the five mandatory fields missing.
• Credit/Debit Notes linked to incorrect UUIDs or to invoices not yet submitted to ZATCA.
• Invoices are archived as plain PDF files without the ZATCA-validated XML embedded.
• Exceeding the 24-hour reporting window for simplified B2C invoices.

The Most Impactful Integration Errors — Detailed Causes and Solutions

ZATCA errors in Phase 2 fall into three primary categories: Business Rule violations (BR errors), XML Schema Validation failures, and Infrastructure-level rejections. The Business Rule category is by far the most frequently encountered during integration, and the errors detailed below represent the highest-volume rejection causes observed across activation waves.

1. Duplicate UUIDs & Broken Invoice Counter Value (ICV) Chain ⚠ KSA-9 / BR-KSA-31

Root Cause: Every document — standard invoice, simplified invoice, credit or debit note — requires a globally unique identifier (UUID) generated per RFC 4122 standard. Simultaneously, each document must carry an Invoice Counter Value (ICV) that strictly increments by exactly 1 from the previous document. This error arises during legacy data migration, in multi-server issuance environments, or when an invoice is deleted from the database while its counter value remains cached.

2. Expired Cryptographic Stamp (CSID) or Invalid OTP During Device Onboarding ⚠ CSID Expiry / OTP Mismatch

Root Cause: The CSID is an X.509 certificate issued by ZATCA for each registered EGS device, typically valid for one year. After expiry, the Fatoora Portal API rejects all submissions from that device with a 401 Unauthorized error. Additionally, during new device onboarding, a one-time OTP is generated via the Fatoora Portal with a validity window of only 60 minutes — using an expired OTP causes complete onboarding failure, requiring a full restart of the registration cycle.

3. Incomplete TLV Encoding in QR Code — Missing or Malformed Mandatory Fields ⚠ TLV Encoding Error / QR-VAL

Root Cause: The simplified invoice requires a QR code TLV-encoded with exactly five mandatory tags in correct order: Tag 01 Seller Name, Tag 02 VAT Registration Number (TRN), Tag 03 Invoice Timestamp (ISO 8601), Tag 04 Total Invoice Amount with VAT, Tag 05 VAT Amount. Any error in tag ordering, field length byte, value formatting, or Base64 encoding produces a QR code that fails ZATCA's validation engine.

4. XML Schema Validation Failure — ZATCA UBL 2.1 Schema Non-Compliance ⚠ XML Schema Validation / UBL-2.1

Root Cause: ZATCA requires every invoice to be an XML file that precisely conforms to the UBL 2.1 schema as extended by ZATCA's specific requirements. Common failures include: absent or incorrect XML namespace declarations, wrong element ordering per the XSD schema, null values in mandatory fields such as InvoiceTypeCode or TaxAmount, incorrect text encoding (must be UTF-8 without BOM), and UBL Extension elements for digital signatures or stamps that do not match the ZATCA-extension schema.

Quick API Error Reference Table (ZATCA Integration)



The Workflow Guide: Clearance vs. Reporting

The Critical Difference Between Clearance and Reporting Workflows

The most prevalent misconception among businesses newly entering Phase 2 is the conflation of the clearance and reporting workflows. Each invoice type follows a completely distinct API pathway, operates on a different timeline, and carries different legal implications. Confusing these workflows does not merely produce a technical error — it can result in a legally non-compliant invoice even if the Fatoora Portal technically accepts it.

Workflow 1: Real-Time Clearance — Standard Tax Invoice (B2B)

In the clearance workflow, the invoice must be submitted to ZATCA and receive cryptographic approval before it is delivered to the buyer. The correct operational sequence is:

• Generate the UBL 2.1-compliant XML invoice with all mandatory ZATCA fields populated.
• Sign the XML with the seller's digital signature using the registered CSID certificate.
• Submit the signed XML to the Fatoora Portal's clearance API endpoint.
• Receive ZATCA's response containing the XML, stamped with ZATCA's cryptographic seal.
• Embed the stamped XML into a PDF/A-3b file and then deliver the invoice to the buyer.

An invoice delivered to the buyer before obtaining ZATCA's clearance stamp constitutes an explicit regulatory violation — not a procedural delay. There is zero time flexibility in the clearance workflow. Clearance must be real-time and must precede delivery, without exception.

Workflow 2: The 24-Hour Reporting Rule — Simplified Invoice (B2C)

In the reporting workflow, the simplified invoice is issued and delivered to the customer immediately at the point of sale. However, the system is mandated to report the invoice to the Fatoora Portal within 24 hours of its issuance timestamp. This window is not a grace period — it is the absolute maximum prescribed by ZATCA regulation, and exceeding it exposes the entity to explicit regulatory consequences, including financial penalties.

A critical operational consideration: businesses operating at high simplified invoice volumes — such as retail, fuel stations, and restaurants — may issue thousands of invoices daily. Managing the submission of this volume within a 24-hour window requires a reliable, scalable Batch Reporting engine. Wafeq's built-in automated batch reporting engine handles this without any manual scheduling or intervention.

ZATCA Invoice Comparison: Standard (B2B) vs. Simplified (B2C)



Why Are Credit and Debit Notes the Most-Rejected Document Type?

Credit and Debit Notes represent the highest per-volume rejection rate among all document types in Phase 2 integration. Analysis of rejection patterns reveals that over 70% of these rejections stem from a single root cause: incorrect or absent linkage between the note and its original reference invoice.

Technically, the Credit or Debit Note XML is required to contain a BillingReference element which carries the exact UUID of the original invoice, character for character. A UUID is a 36-character string in a fixed format (8-4-4-4-12), and any error, even in a single character or letter case, produces an immediate API rejection from ZATCA. Furthermore, the referenced invoice must have completed the clearance or reporting cycle — it is not possible to issue a Credit Note against an invoice that has not yet been submitted to the Fatoora Portal.

The Primary Causes of Credit/Debit Note Rejections

• Incorrect UUID — wrong characters, wrong case (uppercase vs lowercase), or truncated.
• Referenced invoice is still in Draft status and has not yet been submitted to ZATCA.
• Using the Invoice Number instead of the UUID in the BillingReference field.
• Wrong DocumentTypeCode — must be '383' for Credit Note, '381' for Debit Note.
• ReasonCode not drawn from ZATCA's approved list of valid reason codes.
• Note value exceeds the original invoice value without a valid sequential justification.

Wafeq automatically validates the BillingReference UUID against the internal invoice archive and confirms the original invoice's clearance or reporting status before permitting note issuance. It also auto-applies the correct DocumentTypeCode and ReasonCode values per ZATCA's approved UBL code lists.



Audit Readiness: PDF/A-3 & Legal XML Archiving

PDF/A-3 and Embedded XML — What Is the True Legal Document?

One of the most widespread misconceptions among Saudi businesses in the Integration Phase is the belief that the PDF file sent to the customer constitutes the e-invoice. Under ZATCA's technical and legal requirements, the true legal document is the digitally signed and ZATCA-stamped XML file. The PDF is merely a human-readable visual representation — it carries no independent legal weight when separated from the XML embedded within it.

The PDF/A-3 standard is a specialized archival variant of the PDF format, designed specifically for long-term document preservation. Its critical differentiator from standard PDF is the ability to embed attachment files within the PDF structure as part of its specification. When the ZATCA-stamped XML file is embedded inside a PDF/A-3b file, the result is a two-layer document: a visual layer that humans read, and a legal layer that systems validate and authorities audit.

What Does a ZATCA Auditor Look for in Your Invoice Archive?

During any Phase 2-related tax audit, ZATCA has the authority to request any invoice and validate it by reading the embedded XML directly. The auditor will verify:

• Validity of the seller's digital signature and its match with the registered CSID.
• Validity of ZATCA's cryptographic stamp and the clearance or reporting timestamp.
• Integrity of the invoice hash matches the value recorded in the cryptographic stamp.
• Completeness of all mandatory fields in the UBL 2.1 schema.
• Correct sequential ordering of UUID and ICV across all invoice documents.

An archive consisting of plain PDF files or unsigned XML cannot satisfy any of these verification points — and therefore does not constitute a compliant tax archive. Companies that discover this deficiency during an audit find themselves in a severe legal position with very limited remediation options.

Wafeq ensures that every invoice is automatically saved as a PDF/A-3b file with the ZATCA-stamped XML embedded inside, and that the complete archive is searchable and immediately available for any audit request without preparation time.

Document Classification & Legal Compliance (ZATCA)



ZATCA Phase 2: The New Equation of Compliance

What began as a shift in invoice issuance format has evolved into a comprehensive technical ecosystem requiring Saudi businesses to invest in genuine digital infrastructure. Phase 2 requirements are not temporary complexities that will diminish — they represent the permanent architecture of tax compliance in the Kingdom of Saudi Arabia for the foreseeable future, and they will grow more precise with every new activation wave.

In this guide, we have examined the most frequently occurring API rejection errors, the correct operational methodologies for real-time clearance and 24-hour reporting, the precise technical requirements for Credit and Debit Notes, and the legal framework for PDF/A-3b invoice archiving. All of these technical, legal, and operational complexities are handled automatically and entirely behind the scenes when using Wafeq E-invoicing.

What Does Wafeq Handle Completely on Your Behalf?

Wafeq eliminates technical complexity by automating the most critical compliance requirements, ensuring your business stays ahead of regulatory changes without manual intervention.

• RFC 4122-compliant UUID generation for every document with a centralized ICV registry.
• Full CSID lifecycle management with proactive renewal alerts 30 days before expiry.
• ZATCA-spec TLV QR code generation with automatic validation of all five mandatory fields.
• Real-time clearance for B2B invoices and an automated batch reporting engine for B2C.
• Full Credit/Debit Note Billing Reference validation against the cleared invoice archive.
• Automatic PDF/A-3b archiving with embedded stamped XML ready for immediate audit access.
• Specialized ZATCA technical support from a team deeply versed in Saudi regulatory requirements.

Business owners and CFOs who appreciate the depth of these technical requirements understand that investing in an invoicing system purpose-built for ZATCA compliance is not an optional upgrade — it is a fundamental risk management decision. The cost of repeated API rejections from the Fatoora Portal, penalties for exceeding the 24-hour reporting window, and legal consequences of a non-compliant archive far exceed the cost of a specialized, certified compliance solution.

Don't face your ZATCA activation wave alone. Let Wafeq E-invoicing handle the full integration, and let you and your finance team focus entirely on what drives your business forward.

Read Also: E-Invoicing Fines in Saudi Arabia: What You Need to Know About ZATCA Penalties

FAQs about ZATCA Phase 2 invoices

What is the minimum revenue threshold for ZATCA Phase 2?

Businesses with VAT turnover exceeding SAR 750,000 in 2022, 2023, or 2024 fall under Wave 23, with a compliance deadline of March 31, 2026. ZATCA notifies each business directly ~6 months before their go-live date. You can verify your wave status on the Fatoora Portal using your VAT registration number.

What are the penalties for non-compliance with ZATCA Phase 2?

Penalties range from SAR 5,000 for not issuing e-invoices, SAR 10,000 for missing a compliant QR code or altering a submitted invoice, up to SAR 50,000 per violation for real-time reporting failures under Article 45 of the VAT Law.

Can I use my existing ERP system for ZATCA Phase 2?

Yes, if your ERP supports API integration. You can add a ZATCA-compliant middleware layer without replacing your system. If your ERP cannot produce UBL 2.1 XML signed with ECDSA, you will need a purpose-built solution like Wafeq E-invoicing.

What happens if the Fatoorah Portal is down and I cannot submit my invoice?

You must report the outage to ZATCA immediately — failing to report carries a penalty. Your invoicing system should queue invoices locally and retry automatically. B2C invoices have a 24-hour buffer; B2B invoices must wait for connectivity before delivery.

How long must businesses retain e-invoices in Saudi Arabia?

ZATCA requires all e-invoices to be retained for a minimum of 5 years in a secure, auditable format. The compliant format is PDF/A-3b with the ZATCA-stamped XML embedded inside. Plain PDF files without embedded XML do not meet this requirement.

How do I fix the ZATCA error BR-KSA-31?

BR-KSA-31 is an Invoice Counter Value (ICV) sequence break. Do not resubmit with the same ICV. Identify the last ZATCA-accepted ICV, then reissue the invoice at ICV + 1. Prevent recurrence with a centralized ICV registry and database-level locking.

Do I need a separate CSID for each branch or POS terminal?

Yes — each EGS device that independently signs and submits invoices requires its own CSID. If invoices are generated by a single central server, only that server needs a CSID. The certificate is tied to the signing system, not the physical location.

Can I issue ZATCA Phase 2 invoices in a foreign currency?

Yes, but the VAT amount and invoice total must always appear in SAR as a secondary currency in the XML. You must use the official SAMA exchange rate on the invoice date and declare it in the XML. The TLV QR code must also reflect SAR equivalent values.

What is the difference between a Compliance CSID and a Production CSID?

The Compliance CSID is for sandbox testing only and has no legal effect. The Production CSID is used for real invoice submissions. Using a Compliance CSID on live invoices causes API-403 errors. You must pass all 12 ZATCA compliance tests before requesting a Production CSID.

How should I invoice non-VAT-registered buyers or government entities?

Sales to consumers (B2C) always use a Simplified Invoice regardless of buyer VAT status. Sales to government or VAT-exempt entities use a Standard Invoice (B2B) with a national ID or commercial registration number in place of a VAT number. Never downgrade B2B to simplified to avoid clearance.