ZATCA Phase 2 Integration: Technical Requirements for Saudi E-Invoicing

Understanding Phase 2 Integration

ZATCA Phase 2 (Integration Phase) transforms e-invoicing from a local generation requirement into a real-time government clearing system. Your invoicing system must communicate with ZATCA's FATOORAH platform before you can issue invoices to customers.

ZATCA Phase 2 (Integration Phase) transforms e-invoicing from a local generation requirement into a real-time government clearing system. Your invoicing system must communicate with ZATCA's FATOORAH platform before you can issue invoices to customers.

The Integration Flow

For Standard (B2B) Invoices — Clearance Model

1. Generate — your system creates the invoice in UBL 2.1 XML format
2. Sign — apply your Cryptographic Stamp Identifier (CSID) to the invoice
3. Submit — send the signed XML to ZATCA's Clearance API
4. Validation — ZATCA validates format, VAT calculations, and tax IDs
5. Clearance — ZATCA adds its cryptographic stamp and returns the cleared invoice
6. Share — only the ZATCA-stamped invoice can be shared with the buyer

B2B invoices are cleared in near-real-time. If ZATCA rejects the invoice, you must fix the issues and resubmit before you can send it to your customer.

For Simplified (B2C) Invoices — Reporting Model

1. Generate and sign — same as above
2. Issue to customer immediately — no need to wait for ZATCA clearance
3. Report to ZATCA within 24 hours — submit the signed XML for reporting

Simplified invoices use a reporting model because B2C transactions need to happen instantly at point of sale.

Technical Requirements

XML Format: UBL 2.1

All invoices must conform to the Universal Business Language (UBL) 2.1 standard with ZATCA-specific extensions. Key elements:

• Invoice/ProfileID — "reporting:1.0" for B2C, "clearance:1.0" for B2B
• Invoice/ID — unique invoice number
• Invoice/IssueDate and Invoice/IssueTime
• Invoice/InvoiceTypeCode — 388 (standard), 381 (credit), 383 (debit)
• AccountingSupplierParty — seller details including VAT registration
• AccountingCustomerParty — buyer details (mandatory for B2B)
• TaxTotal — per-line and invoice-level tax calculations
• LegalMonetaryTotal — line extension amount, tax exclusive, tax inclusive, payable

Cryptographic Stamp Identifier (CSID)

Before you can submit invoices, you must onboard with ZATCA to receive your CSID:

1. Generate a Certificate Signing Request (CSR) using ECDSA (secp256k1)
2. Submit the CSR to ZATCA's onboarding API
3. Receive your Compliance CSID for testing
4. Pass compliance checks by submitting sample invoices
5. Receive your Production CSID for live invoicing

Invoice Hashing

Each invoice includes a hash of the previous invoice, creating a chain of integrity:

• The first invoice hashes a base64-encoded seed value
• Each subsequent invoice includes the hash of the previous invoice's XML
• This makes it impossible to delete or modify historical invoices without breaking the chain

Onboarding Process

Onboarding Process includes: Register on ZATCA's developer portal — get API credentials Set up your sandbox environment — ZATCA provides a test API

1. Register on ZATCA's developer portal — get API credentials
2. Set up your sandbox environment — ZATCA provides a test API
3. Generate your CSR and obtain Compliance CSID
4. Submit compliance test invoices — ZATCA verifies your implementation
5. Obtain Production CSID — you're cleared for live invoicing
6. Go live — start submitting real invoices to the clearance/reporting API

Common Integration Challenges

Common Integration Challenges includes: Arabic character encoding — seller names must be in Arabic (UTF-8).

• Arabic character encoding — seller names must be in Arabic (UTF-8). Ensure your system handles RTL text correctly
• Time zone handling — all timestamps must be in Saudi Arabia time (AST/UTC+3)
• Invoice counter management — the sequential counter must never reset or have gaps
• Hash chain integrity — if you need to void an invoice, you issue a credit note; you cannot delete the original
• CSID renewal — CSIDs expire and must be renewed before expiry

Getting Started

While full Phase 2 API integration requires technical implementation, you can start creating ZATCA-compliant invoices today with the right invoicing software.

While full Phase 2 API integration requires technical implementation, you can start creating ZATCA-compliant invoices today with the right invoicing software. Create a Saudi VAT invoice →