ZATCA E-Invoicing Phase 2 Portal Onboarding Steps
A step-by-step walkthrough of the Fatoora portal OTP flow, CSID issuance, and integration handshake — so your first production call clears without rejection codes.
By the SuperAccountant Editorial Team
Most teams treating Phase 2 onboarding as a one-day task end up spending a week chasing OTP errors and certificate mismatches. The Fatoora portal flow has a precise sequence — skip a step or misread the sandbox versus production boundary and your ERP will throw rejection codes on live invoices. Here is the exact sequence, the common failure points, and what to verify before you flip the switch.
Why Phase 2 Onboarding Is Not a Repeat of Phase 1
Phase 1 (generation) required structured XML and a QR code. Phase 2 (integration) adds a real-time API handshake with ZATCA's Fatoora platform. According to ZATCA's e-invoicing portal, the taxpayer's solution must obtain a Cryptographic Stamp Identifier (CSID) per device or ERP instance, clear every B2B invoice before issuance, and report B2C invoices within 24 hours.
The practical consequence: your finance team cannot manually post a B2B invoice and send a PDF. Every invoice leaves your system only after ZATCA's API returns an HTTP 200 with clearance status embedded in the XML.
ZATCA's rollout is wave-based. Confirm your wave date on the official portal — penalties under ZATCA E-Invoicing Implementing Regulation Article 53 start from the day your wave goes live, not from when you discover the requirement.
The Five-Stage Onboarding Flow on the Fatoora Portal
Think of onboarding as a pipeline. Each stage gates the next.
| Stage | Action | Output |
|---|---|---|
| 1 | Register your solution on the Fatoora portal | Integration card with Solution ID |
| 2 | Generate a Certificate Signing Request (CSR) in your ERP/SDK | CSR file (.pem) |
| 3 | Submit CSR via portal → receive OTP | One-time password (6-digit, 1-hour TTL) |
| 4 | Exchange OTP + CSR for Compliance CSID | Compliance certificate (X.509) |
| 5 | Run compliance checks → exchange for Production CSID | Production certificate — you are live |
Miss the 1-hour OTP window and you restart from Stage 3. Multiple teams have wasted days here because the OTP email landed in a shared mailbox no one monitors.
Stage-by-Stage: What to Do on the Fatoora Portal
Stage 1 — Register your solution
Log in to fatora.zatca.gov.sa using the taxpayer's Nafath-authenticated account. Navigate to My Solutions → Add New Solution. You will name the solution (e.g., "SAP S/4HANA – Entity A") and receive an Integration Card containing your Solution ID and API credentials for sandbox.
One entity, multiple branches or ERPs = one Integration Card per device/instance. A company with three warehouse systems needs three cards, three CSIDs, and three certificates.
Stage 2 — Generate the CSR
This step happens inside your ERP or ZATCA-compliant SDK, not the portal. The CSR must include specific OIDs mandated by ZATCA's technical specifications (v3.2 of the E-Invoicing Technical Specification, available on the portal). Required fields include:
- EIN (Entity Identification Number = your VAT registration number)
- CRN (Commercial Registration Number)
- Solution Name (must match the portal entry exactly — case-sensitive)
- Invoice type flag: 0100 (Tax Invoice), 0010 (Simplified), or 1100 (both)
A mismatch between the CSR OID values and your portal registration is the single most common reason for Stage 4 failure. Validate the CSR with an ASN.1 parser before submission.
Stage 3 — Submit CSR and collect OTP
Upload the CSR on the portal under Onboarding → Submit CSR. The portal immediately issues a 6-digit OTP to the registered email and displays a reference number. Set a 55-minute timer — do not let the OTP expire.
Stage 4 — Compliance CSID
Pass the OTP and CSR to ZATCA's compliance API endpoint:
POST /compliance
Host: gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal (sandbox)
Host: gw-fatoora.zatca.gov.sa/e-invoicing/core (production)
A successful call returns your Compliance CSID (X.509 certificate) and a Secret key. Store the secret securely — ZATCA does not reissue it. If you lose it, you must re-onboard from Stage 1.
Stage 5 — Compliance Checks and Production CSID
Before production access, you must pass ZATCA's compliance check API by submitting a set of test invoices — typically six scenarios (standard tax invoice, simplified tax invoice, credit note, debit note, and their simplified equivalents). Each must clear without error. Once all scenarios return compliant status, call:
POST /production/csids
with your compliance token. The response contains your Production CSID. From this point, every clearance and reporting call uses this certificate.
Common Onboarding Pitfalls and How to Avoid Them
OTP timeout — Assign a dedicated email alias monitored in real time. The OTP has a 1-hour TTL. Pre-stage your API call before submitting the CSR.
CSR OID mismatch — Pull the exact OID definitions from ZATCA's technical specification, not from a third-party blog. The solution name in the CSR must be byte-for-byte identical to the portal entry.
Sandbox leakage into production — Sandbox and production use different base URLs and different certificates. Hardcoding the sandbox URL in a .env file and promoting the same file to production is a recurring error. Separate your environment configs explicitly.
Certificate expiry — Production CSIDs are valid for one year. Calendar a renewal task at T-30 days. ZATCA's Implementing Regulation does not grant a grace period for expired certificates — cleared invoices will start rejecting immediately.
Invoice counter sequence — ZATCA enforces a monotonically increasing invoice counter (ICV) per CSID. A failover or ERP migration that resets the counter will cause rejection. Your ICV must persist across reboots and deployments.
Mu'tamad ERP consideration — If your client uses a Mu'tamad-listed ERP (the ZATCA-approved solutions list), the ERP vendor typically handles the CSR generation. However, the Integration Card registration on the Fatoora portal remains the taxpayer's responsibility. Do not assume the vendor handles the portal steps.
What the Clearance API Response Tells You
Every cleared B2B invoice API response (HTTP 200) returns:
- Cleared XML — store this, not your original. The cleared XML contains ZATCA's stamp and is the legally valid document.
- Clearance status —
CLEAREDorNOT_YET_CLEARED. OnlyCLEAREDmeans you can issue to the buyer. - Warnings — ZATCA may clear an invoice and still return warnings (e.g., field format advisory). Warnings do not block the invoice but must be reviewed and resolved in future submissions per your implementation roadmap.
For B2C (simplified invoices), the reporting API accepts batches of up to 100 invoices. The 24-hour reporting window runs from the invoice timestamp, not the end of the business day.
Pre-Go-Live Checklist for Your Finance and IT Teams
Before moving to the production CSID, confirm each of the following:
- Integration Card registered on Fatoora portal with correct entity details
- CSR OIDs validated against ZATCA Technical Specification v3.2
- OTP collected and compliance CSID issued without errors
- All six compliance check scenarios passed with
COMPLIANTstatus - Production CSID stored in secure secrets manager (not plaintext config)
- Certificate expiry date calendared with T-30 renewal alert
- ICV counter persistence tested across ERP restart
- Sandbox and production environment variables separated
- Cleared XML archival process confirmed (ZATCA requires 6-year retention under VAT Implementing Regulation Article 66)
- Finance team briefed: no B2B invoice leaves the system without HTTP 200 clearance confirmation
Running through this list with your client before wave go-live takes two hours. Skipping it costs two weeks of incident management.
Keeping Your Skills Current on Phase 2 Implementation
The technical specification has been updated multiple times since Phase 2 launched. If you are advising clients on their integration process, reviewing the ZATCA e-invoicing developer portal before each engagement is non-negotiable — version drift between your implementation notes and the current spec is a real risk.
For practitioners who want structured, hands-on practice with Phase 2 scenarios — including working through the CSR-to-CSID flow with real test environments — test yourself on our ZATCA e-invoicing quiz to benchmark where your gaps are before committing to client work.
Sharpen your edge with SuperAccountant's next live cohort — small batches, real client workpapers, taught by partners. Details and seats at https://app.superaccountant.in/en/cohort?utm_source=blog&utm_medium=cta&utm_campaign=accountants.