Zatca Phase 2 Integration: 5 Steps to Avoid Onboarding Errors



Why Is ZATCA Phase 2 Onboarding More Technical Than You Expected — And How Do You Complete It Correctly?

Direct Answer: For Wave 10 and beyond, ZATCA Phase 2 compliance begins not with an invoice, but with a cryptographic handshake between your invoicing system and the Fatoora Portal. The Cryptographic Stamp Identifier (CSID) is the digital certificate that authorizes your system to issue, sign, and submit legally valid e-invoices — and without it, not a single invoice you issue carries legal weight under Saudi tax law.

This guide walks you through the exact technical execution of the Phase 2 onboarding process. By the end, you will have the operational clarity to:

• Understand what a Certificate Signing Request (CSR) is and why it is your system's unique digital fingerprint.
• Retrieve your OTP from the Fatoora Portal and use it correctly before the 60-minute window closes.
• Test safely in the ZATCA Simulation environment and pass all 12 compliance scenarios before going live.
• Understand what the Production CSID is and what it means when it is loaded into Wafeq.
• Appreciate how Wafeq compresses weeks of technical complexity into a guided process that takes minutes.

The Technical Handshake: A Comprehensive Wave 10+ Guide to ZATCA Phase 2 Onboarding

Saudi Arabia's e-invoicing journey has reached a phase that demands more than intent — it demands real digital infrastructure. Wave 10 and all subsequent waves represent a landmark expansion of ZATCA's Phase 2 mandate, drawing in thousands of mid-market businesses, regional companies, professional services firms, and independent accountants who have never before interfaced directly with a government cryptographic infrastructure. These businesses are entering a fundamentally different tax era from anything they have previously known.

In Phase 1, compliance meant generating a structured digital invoice with a QR code and storing it. At its core, it was a conversion from paper to digital. In Phase 2, the requirement has leaped qualitatively: your invoicing system must communicate with ZATCA's Fatoorah Platform via a sequence of cryptographic exchanges, digital certificate issuance, and mutual API authentication. All of this before a single live invoice is ever issued. An invoice that bypasses this handshake is not a legal invoice — it is merely an electronic document with no recognized tax standing in the Kingdom.

What is the Cryptographic Stamp?

At the heart of this entire architecture sits the Cryptographic Stamp. This is not a metaphor or a marketing term. It is a precise technical mechanism: an X.509 digital certificate issued by ZATCA's Certificate Authority (ZATCA CA) that uniquely identifies your E-Invoicing Generation Solution (EGS), authorizes it to sign invoices with a ZATCA-recognized cryptographic signature, and creates an immutable, tamper-proof record proving that every invoice you issue is authentic, unaltered, and traceable to your registered business identity. Without the Cryptographic Stamp, your EGS does not exist in ZATCA's system. Without it, your invoices are legally invisible and vulnerable to challenge in any tax audit.

The question facing thousands of Saudi businesses today is not "must we comply?" — it is "how do we complete this technical onboarding correctly without disrupting our business operations?" That is precisely what this guide answers with full operational detail.

The onboarding process for Phase 2 — officially termed EGS Onboarding by ZATCA — consists of sequential stages, each with its own logic and precise requirements:

• CSR generation.
• OTP retrieval.
• Simulation testing.
• Compliance CSID acquisition.
• the 12-scenario test suite.
• and finally, Production CSID issuance that authorizes live invoice submission. An error at any stage stops the entire process.

This guide translates ZATCA's Technical Guidelines from dense regulatory language into a practical, step-by-step roadmap for execution that your finance and IT teams can follow from start to finish.

Part 1: The CSR Simplified — Your System's Digital Fingerprint

Before ZATCA issues your Cryptographic Stamp, it needs proof of who you are — not just as a VAT-registered business entity, but as a specific technical system operating at a specific address with a unique cryptographic identity. This proof takes the form of a Certificate Signing Request, which is also called CSR.

Think of the CSR as the digital fingerprint of your invoicing device. Just as no two human fingerprints are identical anywhere in the world, no two CSRs are the same — each is cryptographically unique to the specific EGS unit being registered on the Fatoora Portal. But unlike a human fingerprint, which is passively imprinted, a CSR is something your system actively constructs and submits electronically — and it carries inside it a mathematical proof of your identity that cannot be forged.

How the Cryptographic Key Pair Works: Private Key and Public Key

Technically, CSR generation begins with creating a Cryptographic Key Pair. This consists of two mathematically linked keys connected by a one-way relationship that cannot be reversed: a Private Key and a Public Key. The relationship between them is unique: what is encrypted with the Private Key can only be decrypted with the corresponding Public Key, and vice versa. This is the foundation of Public Key Infrastructure (PKI) on which all ZATCA certificates are built.

The Private Key is generated on your side and must never leave your system — not even to ZATCA itself. It is the key that will sign every invoice you issue, creating a unique digital signature that proves the invoice was issued by your specific registered device and has not been altered by even a single character since it was signed. The Public Key is the counterpart that is freely distributed and can be used by anyone — including ZATCA, buyers, and judicial authorities — to verify the validity of that signature without revealing anything about your Private Key. Together, they form the complete trust foundation of your entire e-invoicing operation.

What Data Does a CSR Contain?

The CSR bundles your Public Key together with the critical business identification data that distinguishes you in ZATCA's system. This mandatory data includes:

• the entity's Tax Identification Number (TIN)
• The organization name, as it is registered with the Authority.
• The unique serial number of the specific EGS unit.
• the environment type (production or testing)
• the invoice types the system will issue (standard B2B, simplified B2C, or both)
• the VAT registration number.
• the issuer role (whether the invoice issuer is the taxpayer themselves or a third party acting on their behalf).

This entire bundle is then cryptographically signed with your Private Key and submitted to ZATCA's Certificate Authority via the Fatoora Portal, paired with the OTP you will retrieve.

ZATCA's Certificate Authority then verifies all the information and cross-references your TIN against its registered taxpayer database. If everything matches and the OTP is valid, it returns a signed Compliance CSID. This Compliance CSID is your entry ticket to the testing stage and the first confirmation that ZATCA has accepted your technical identity. However, it is not the certificate you will use for live invoices — that comes later.

How Wafeq Automates This Entire Process — With Zero Manual Input

Generating a cryptographically correct key pair and constructing a properly formatted CSR requires expertise in cryptographic libraries (such as OpenSSL or BouncyCastle), correct ASN.1 encoding, and precise compliance with the technical specifications documented in ZATCA's Technical Guidelines. This is far removed from the domain of finance and accounting teams. That is precisely why Wafeq handles this entire process automatically.

The Private Key is generated within Wafeq's secure, encrypted vault using the ECDSA (Elliptic Curve Digital Signature Algorithm) specified by ZATCA — and it never leaves the system in unencrypted form. The Public Key is packaged into a correctly formatted CSR with all mandatory fields pre-populated from your Wafeq account data automatically. You never see, touch, or interact with raw cryptographic material at any stage. Wafeq's onboarding interface guides you through the single input that requires action from you: the OTP from the Fatoora Portal.

Also Read: A detailed and in-depth guide on setting up the e-invoicing module in Wafeq for Saudi companies

Part 2: The OTP Race — A 60-Minute Window That Waits for No One

The One-Time Password (OTP) is the security bridge between the Fatoora Portal's record of your business and the CSR your system generates. It is ZATCA's anti-spoofing mechanism confirming that the person or system initiating the registration on the Fatoora Portal is the same entity that holds the CSR being submitted, ensuring no third party can register an EGS on your behalf without your direct, explicit authorization. The OTP can only be generated from the Fatoora Portal itself; no other source can produce a valid OTP regardless of its claimed authority.

ZATCA provides two methods for generating and using the OTP: the manual method, where it is generated from the Fatoora Portal via a browser, copied, and entered manually into the EGS system, which allows onboarding multiple devices simultaneously in a single session; and the automated method, where the EGS communicates with the Fatoora Portal directly via API and reads the OTP automatically, which only allows onboarding one device per cycle. Wafeq supports both methods, though the manual method is the most commonly used and accessible for businesses in their initial onboarding phase.

Step-by-Step: How to Fetch Your OTP from the Fatoora Portal

1. Log in to the Fatoora Portal: Access the portal using your ZATCA Taxpayer Portal credentials via Single Sign-On (SSO). You will need the email address and password registered with your official VAT account. Confirm that you have the administrative permissions required before starting — attempting to generate OTPs without the correct role results in an access error.
2. Select "Onboard New Solution Unit/Device": On the Fatoora Portal landing page, you will find a set of functional tiles. Click the "Onboard New Solution Unit/Device" tile specifically. This is the dedicated workflow for first-time EGS registration. Do not use the "Renew CSID" tile — that is for renewing existing certificates, not for initial onboarding of new devices.
3. Specify the exact number of EGS units: Enter precisely how many EGS units you wish to onboard in this session. If you have 5 branches, each with an independent server, enter 5. If you have 3 separate POS terminals, enter 3. The Portal will generate OTPs matching the number you specify — each OTP is unique to its device and cannot be used for a different device.
4. Generate, copy, and secure your OTPs: The Portal generates one unique OTP per EGS unit and displays it on screen. You can copy each one manually or download a file containing all generated OTPs. Note the exact generation timestamp carefully — this is the precise moment the 60-minute countdown begins for each OTP, and it cannot be paused or extended under any circumstances.
5. Enter the OTP in Wafeq immediately without delay: Navigate directly to Wafeq, open the ZATCA Integration setup page, enter the OTP along with the EGS unit name and any required configuration details, and initiate the onboarding process. Wafeq's system takes over from this point automatically: it completes the CSR construction, pairs the CSR with the OTP, submits both to ZATCA's API, receives the Compliance CSID, and stores it securely — all within seconds.

Part 3: The Safety Net — Simulation Environment vs. Production Environment

Before any live invoice reaches ZATCA's production environment, every business undergoing Phase 2 onboarding has access to an invaluable tool: the ZATCA Simulation Portal (also known as the Sandbox Environment). This is not a simplified testing tool — it is a fully functional replica of the live Fatoora Portal that runs the same validation engines, the same XML rules, and API structure, but operates on test data without any legal consequences.

Businesses that skip the Simulation stage and proceed directly to Production — whether out of impatience or unawareness of the requirements — pay a steep price. XML errors that appear as correctable warnings in Simulation become hard, unrecoverable rejections in Production, with formal rejection records against your compliance file. Schema violations that are easy to debug in testing become API-403 responses in live operation that block your entire invoice flow. Using the Simulation environment is not an optional best practice — it is the only responsible way to approach a Phase 2 go-live.

Full Comparison Table: Simulation Environment vs. Production Environment



The 12 Mandatory ZATCA Compliance Test Scenarios — What They Cover and How to Pass Them

ZATCA requires every EGS system to pass a standardized set of compliance test scenarios before a Production CSID is issued. These scenarios are designed to test the system's ability to generate correct XML across all invoice types and edge cases that may be encountered in real business operations. Each scenario evaluates a different aspect of the system's technical and business rule compliance.

• Standard B2B Tax Invoices: A standard tax invoice, a linked credit note, and a linked debit note — 3 scenarios
• Simplified B2C Tax Invoices: A simplified invoice, a linked credit note, and a linked debit note — 3 scenarios
• Tax Edge Cases: An invoice with zero-VAT line items, an invoice with VAT-exempt items, and an invoice with mixed tax rate categories — 3 scenarios
• Special Case Scenarios: Invoices with foreign currency and SAR equivalent, and additional scenarios based on the invoice types declared in the CSR — 3 scenarios

Read Also: Why Does the Invoice Title Sometimes Say "Simplified Tax Invoice" Instead of "Tax Invoice"?

Failing any scenario in Simulation is not a problem — it is the tool working exactly as designed. Fix the XML, resubmit, and iterate until all 12 pass. Only then should you proceed to request your Production CSID. Failing in Production — after having bypassed Simulation — is a scenario that should never occur if the process is followed correctly.

Wafeq's testing approach: Wafeq runs automated pre-flight checks against all 12 compliance scenarios within its built-in test environment before presenting you with the Production CSID request. You do not need to manually construct test invoices, interpret raw API responses, or track any scenario manually. Wafeq's compliance engine handles the full test cycle and only alerts you if a specific scenario requires data from you or a corrective action on your part.

Part 4: The Result — The Production CSID and the Completed Handshake

After your Compliance CSID has been successfully used to pass all 12 compliance test scenarios in the Simulation environment, you are ready for the final and most critical step: requesting your Production CSID. This request is submitted to ZATCA using the Request ID received when you obtained your Compliance CSID in the first stage. This link between the two certificates proves to ZATCA that you have completed the full testing cycle properly.

The Production CSID — the Cryptographic Stamp Identifier — is the culmination of everything described in this guide and the official beginning of your live operational existence in Phase 2. It is a signed X.509 certificate issued by ZATCA's Certificate Authority that cryptographically binds your Public Key to your registered business identity and the serial number of your specific EGS unit. From this moment forward, every invoice you issue carries the authority of this certificate.

Core Properties of the Production CSID

• Validity: Exactly one year from the date of issuance. Renewal procedures must be initiated before expiry to ensure uninterrupted invoice operations.
• Scope: Tied exclusively to a single EGS unit — each independent invoicing device requires its own Production CSID. A CSID cannot be shared between multiple devices under any circumstances.
• Security: The corresponding Private Key must be stored in a secure, encrypted vault at all times. If compromised or suspected of exposure, the CSID must be immediately revoked via the Fatoora Portal, and a new one requested.
• Technical Function: Signs every invoice XML file with a ZATCA-recognized ECDSA digital signature, making the invoice legally valid and cryptographically verifiable by any party holding your Public Key.
• Required Storage: Must be kept in a secure, encrypted vault — never stored as plain text, in an unsecured database, or in an unprotected file.
• Renewal Process: Mirrors the initial onboarding — a new OTP from the Fatoora Portal via the "Renew CSID" tile, plus a renewal CSR submission. No new compliance test scenarios are required at renewal time.

Once the Production CSID is loaded into Wafeq, the technical handshake is officially complete. Your Wafeq account is now a fully authorized, ZATCA-registered E-Invoicing Generation Solution. Every invoice you issue from this point carries ZATCA's cryptographic endorsement, embeds your unique digital signature, and flows through the correct API endpoint — the clearance endpoint for standard B2B invoices requiring real-time ZATCA approval, or the reporting endpoint for simplified B2C invoices subject to the 24-hour submission window — automatically, in the background, with no additional action required from your finance team or IT department for each invoice.

Complete Onboarding Checklist: ZATCA Phase 2 Integration

Use this checklist as your operational reference to confirm each onboarding step is complete before proceeding to the next. Every item represents a mandatory requirement that cannot be skipped.

□ Confirm your entity falls within an active ZATCA activation wave and that you have received (or verified) your official notification

□ Implement a Phase 2-compliant e-invoicing system (such as Wafeq) capable of generating UBL 2.1 XML and signing it with ECDSA

□ Generate the cryptographic key pair (Private + Public Key) and secure the Private Key in an encrypted vault

□ Construct the CSR with all mandatory fields (TIN, name, invoice types, VAT number) in correct X.509 format

□ Log in to the Fatoora Portal, generate the OTP from "Onboard New Solution Unit", and act within 60 minutes

□ Submit CSR + OTP to ZATCA's API and receive and store the Compliance CSID securely

□ Run and pass all 12 compliance test scenarios in the Simulation environment without exception

□ Request the Production CSID using the Request ID from the Compliance CSID stage

□ Load the Production CSID into the system and submit a live test invoice to confirm production connectivity

□ Set a CSID renewal alert 30 days before expiry (Wafeq handles this automatically)

With Wafeq, the Technical Handshake Takes Minutes, Not Weeks

The onboarding process detailed in this guide — CSR generation, OTP retrieval, Simulation testing, Compliance CSID acquisition, the 12-scenario test suite, and Production CSID issuance — can take an unprepared business weeks of exhausting back-and-forth between IT teams, ZATCA documentation, cryptographic libraries, and the Fatoora Portal. Many businesses entering Wave 10 and beyond are encountering this technical depth for the first time and feel genuinely overwhelmed by what Phase 2 requires behind the scenes.

Wafeq was purpose-built so that this entire process is seamless for your business. The cryptographic key pair is generated automatically. The CSR is constructed with zero manual input from your team. The OTP workflow is embedded directly into Wafeq's setup interface. All 12 compliance scenarios are run and verified automatically. The Production CSID is stored in Wafeq's encrypted vault. Renewal alerts are sent 30 days before expiry. Every element of the technical handshake is handled by Wafeq so that your finance team never has to engage with it directly.

Your finance team should be focused on closing books, analyzing cash flow, and supporting business growth — not deciphering ASN.1 encoding standards, debugging UBL 2.1 XML schemas, or managing cryptographic certificate lifecycles. That is exactly what Wafeq exists to handle.

Read Also: Why is the Fatoorah Portal Rejecting Your Invoices? [Practical Solutions for ZATCA Integration Errors]

FAQs About ZATCA Phase 2 Onboarding

What is a CSR in ZATCA Phase 2, and why is it required?

A CSR (Certificate Signing Request) is a digitally signed electronic document that your EGS generates, containing your Public Key and business identification data. ZATCA uses it to verify your identity and issue your CSID — the certificate that authorizes your system to sign and submit invoices legally. Without a valid CSR, you cannot receive any CSID, and without a CSID, you cannot submit any invoice to the Fatoora Portal or initiate any clearance or reporting operations.

What happens if my OTP expires before I complete the CSR submission?

An expired OTP cannot be reused, extended, or recovered under any circumstances. You must return to the Fatoora Portal, navigate to "Onboard New Solution Unit/Device" again, and generate a completely fresh OTP. You then have a new 60-minute window to complete the submission. The simplest preventive measure: prepare and verify everything in Wafeq fully before opening the Fatoora Portal to generate the OTP — do not open the Portal until you are ready to act immediately.

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

The Compliance CSID is issued after your initial CSR submission and is used exclusively for testing in ZATCA's Simulation environment — it carries no legal standing whatsoever. The Production CSID is issued after you pass all 12 compliance test scenarios and is the certificate used for all live, legally binding invoice submissions. The most common mistake is submitting real invoices using a Compliance CSID, which results in API-403 errors and no invoice acceptance.

How long is a Production CSID valid, and how do I renew it?

A Production CSID is valid for exactly one year from its issuance date. ZATCA requires renewal before expiry to maintain uninterrupted invoice operations. The renewal process mirrors the initial onboarding — you generate a new OTP from the Fatoora Portal via the "Renew CSID" tile and submit a renewal CSR. No new compliance test scenarios are required at renewal time. Wafeq sends automated renewal alerts 30 days before your CSID expiry date to ensure you never face an expiry-driven rejection.

Can I onboard multiple EGS units simultaneously in a single session?

Yes, completely. The Fatoora Portal allows you to generate multiple OTPs in a single session — one per EGS unit — with no theoretical limit on quantity. Each OTP is unique to its specific device, and all carry the same 60-minute validity window starting from their generation timestamp. Large businesses with multiple branches should plan their onboarding session carefully, preparing all systems in advance to ensure every OTP is used within the window before any expire.

What are the 12 mandatory compliance test scenarios, and where can I find them?

ZATCA requires EGS systems to submit test invoices covering: standard B2B tax invoices with linked credit and debit notes (3 scenarios), simplified B2C invoices with their linked notes (3 scenarios), invoices with zero-VAT line items, VAT-exempt items, and mixed tax rate categories (3 scenarios), and special case scenarios including foreign currency invoices and cases based on the invoice types declared in the CSR (3 scenarios). The complete specification is published in ZATCA's official Technical Guidelines on the Developer Portal. Wafeq runs all 12 automatically.

What happens if my Production CSID is compromised or its Private Key is exposed?

If your Production CSID's Private Key is compromised or you suspect unauthorized access, you must immediately revoke the CSID through the Fatoora Portal without any delay. A revoked CSID cannot be restored or reactivated — you must generate a completely new CSR and request a fresh Production CSID. During the revocation and renewal window, your EGS cannot submit any invoices to ZATCA. This is the fundamental reason the Private Key must be stored in a secure, encrypted vault at all times — precisely as Wafeq does automatically.

Is the ZATCA Simulation Portal technically identical to the Production Portal?

The Simulation Portal is a complete functional replica of the live Fatoora Portal, using the identical API structure, the same validation engine, XML schema requirements, and business rule logic. The only three differences are: it operates on test data rather than real transactions, its responses carry no legal effect or tax standing, and it uses Compliance CSIDs rather than Production CSIDs. Every XML error you identify and fix in Simulation is a real error that would have been rejected in Production — making the Simulation environment the ideal space for all pre-launch integration testing and XML debugging.