Direct Answer / Quick Summary:

To onboard an Electronic Generation Solution (EGS)—such as an ERP system (SAP, Oracle, Odoo), accounting platform, or POS cash register—with Saudi Arabia's ZATCA Fatoora Portal for Phase 2 E-Invoicing integration:

Step 1: Generate OTP in Fatoora Portal: Log into the official Fatoora Portal using your ERAD/ZATCA corporate credentials, navigate to Onboard New Solution / Device, and generate a 6-digit One-Time Password (OTP). The OTP is valid for 60 minutes* and can only be used once.

Step 2: Generate Cryptographic Keypair & CSR: Use OpenSSL to generate an ECDSA private key (secp256k1 curve)* and create a Certificate Signing Request (CSR) embedding your Taxpayer VAT Identification Number (TRN), branch location, and unique EGS unit serial number.

Step 3: Obtain Compliance CSID: Send an HTTP `POST` request to ZATCA's `/compliance` API endpoint with the Base64-encoded CSR and the 6-digit OTP in the request header. ZATCA returns a Compliance Cryptographic Stamp Identifier (Compliance CSID)*.

Step 4: Pass Compliance Check Invoices:* Submit the required sample UBL 2.1 XML invoices (Standard & Simplified, Credit & Debit notes) through the compliance validator.

Step 5: Request Production CSID: Call the `/production/csids` endpoint using your Compliance credentials. ZATCA issues the final Production CSID*, authorizing your device to issue legally binding live tax invoices.

What is an EGS Unit & Why is Onboarding Mandatory?

Under the E-Invoicing Regulations promulgated by the Zakat, Tax and Customs Authority (ZATCA) under Royal Decree No. M/113, all taxable enterprises entering Phase 2 (Integration Phase / الربط والتكامل) must cryptographically bind their invoicing software to ZATCA's national ledger.

An Electronic Generation Solution (EGS) refers to any digital system capable of issuing tax invoices, including:

Enterprise Resource Planning (ERP) databases (SAP S/4HANA, Microsoft Dynamics 365, Oracle Fusion, NetSuite).
Localized business applications (Odoo, Zoho Books, QuickBooks, Wafeq).
Retail electronic cash registers and Point-of-Sale (POS) terminals.

Each physical terminal or independent ERP instance must possess its own unique digital identity known as a Cryptographic Stamp Identifier (CSID). Onboarding is the official process that verifies, signs, and authorizes that digital identity.

Step 1Fatoora Web Portal

Fatoora Portal OTP Generation

Taxpayer logs into portal and requests a 6-digit single-use OTP valid for 60 minutes

Step 2Local Server / ERP

Local CSR & Key Generation

Developer executes OpenSSL to create secp256k1 keypair and custom X.509 CSR configuration

Step 3Sandbox / Compliance API

Compliance CSID Issuance

ERP calls ZATCA API passing Base64 CSR and OTP; receives temporary Compliance CSID

Step 4Compliance Engine

Validation Test Run

Device submits required test invoices (Standard & Simplified, Credit/Debit notes) with zero rejections

Step 5Production Engine

Production CSID Activation

Device exchanges Compliance CSID for permanent Production CSID; live clearance enabled

Cryptographic Foundations: Secp256k1 & Custom X.509 OIDs

ZATCA enforces rigorous cryptographic standards. Unlike standard web SSL certificates that often use RSA 2048, ZATCA mandates the Elliptic Curve Digital Signature Algorithm (ECDSA) with the secp256k1 curve (identical to the curve used in blockchain protocols).

Mandatory CSR Subject Fields

When constructing the Certificate Signing Request configuration file (config.cnf), developers must include specific ZATCA Object Identifiers (OIDs) within the Subject Distinguished Name (DN):

Configuration FieldParameter NameRequired Value / Format
Common Name (CN)EGS Serial NumberUnique machine or instance identifier (e.g., EGS1-ACME-001)
Organization Unit (OU)Branch Name / UnitName or code of the operating corporate branch
Organization (O)Taxpayer Legal EntityRegistered commercial company name matching CR
Country (C)Country CodeSA (Kingdom of Saudi Arabia)
UID (OID: 0.9.2342.19200300.100.1.1)VAT Number (TRN)15-digit Tax Registration Number starting and ending in 3
Title (T)Invoice Capability Code1100 (Standard & Simplified), 1000 (Standard only), or 0100 (Simplified only)
Category (registeredAddress)Branch Physical LocationRegistered physical street address of the issuing establishment
Business CategoryIndustry Activity CodePrimary business activity classification

Generating the Private Key & CSR via OpenSSL

To generate compliant credentials on your Linux or Windows server:

bash|Technical Specification / Reference
Verified Schema
# Step A: Generate the secp256k1 private key
openssl ecparam -name secp256k1 -genkey -noout -out private_key.pem

# Step B: Generate the Certificate Signing Request (CSR) using the configuration file
openssl req -new -sha256 -key private_key.pem -extensions v3_req -config config.cnf -out taxpayer_egs.csr

# Step C: Convert CSR to clean single-line Base64 for API transmission
cat taxpayer_egs.csr | base64 -w 0 > csr_base64.txt

Step-by-Step Walkthrough: Generating the 6-Digit OTP on Fatoora Portal

The OTP acts as a secure, pre-authenticated handshake between the taxpayer's legal identity and the developer's API requests:

Step 1: Log in to the ZATCA ERAD Portal

1Navigate to the official tax portal: https://zatca.gov.sa.
2Authenticate using your corporate ERAD credentials or Nafath Business Single Sign-On.
3Select your registered commercial establishment.

Step 2: Access the Fatoora Platform

1From the main tax dashboard, locate the E-Invoicing (Fatoora) Service (منصة فاتورة).
2Click Access Portal (الدخول إلى المنصة).
3You will be redirected to the secure Fatoorah administrative dashboard (fatoora.zatca.gov.sa).

Step 3: Request Onboarding OTP

1In the side navigation bar, click on Onboard New Solution / Unit (تهيئة وحدة جديدة).
2Select whether this device will operate in Simulation (Sandbox) or Production (Live) environment.
3Click Generate OTP (إصدار رمز التحقق).
4The screen will display a 6-digit numeric OTP (e.g., 482910).
5A live countdown timer begins: you have exactly 60 minutes to consume this OTP via API before it expires.

Step-by-Step API Execution: From Compliance to Production CSID

Once you have generated your Base64 CSR and acquired the 6-digit OTP, your ERP integration software executes the cryptographic onboarding exchange:

Step 1: Request Compliance CSID (API Call)

Make an HTTP POST request to the compliance endpoint:

Endpoint URL (Simulation): https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation/compliance
Endpoint URL (Production): https://gw-fatoora.zatca.gov.sa/e-invoicing/core/compliance

Request Headers:

http|Technical Specification / Reference
Verified Schema
POST /e-invoicing/core/compliance HTTP/1.1
Host: gw-fatoora.zatca.gov.sa
Accept-Language: en
Accept-Version: V2
OTP: 482910
Content-Type: application/json

Request JSON Body:

json|Technical Specification / Reference
Verified Schema
{
  "csr": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQmZ6Q0NBVU1DQVFBd1ZE...[Base64_CSR_STRING]..."
}

Expected JSON Response (HTTP 200 OK):

json|Technical Specification / Reference
Verified Schema
{
  "requestID": 1029481,
  "dispositionMessage": "ISSUED",
  "binarySecurityToken": "MIIDqDCCApCgAwIBAgIQZ7x...[Base64_X509_CERTIFICATE]...",
  "secret": "b3f58a9e-4c21-4d92-91f3-1029481a5b8e",
  "errors": null
}
Statutory Compliance Note

Store the binarySecurityToken (which is your Compliance CSID certificate) and the secret safely in your ERP's encrypted configuration vault. You will use these credentials as HTTP Basic Authentication for all subsequent compliance test checks.

Executing the Mandatory Compliance Invoicing Matrix

Before ZATCA allows an EGS unit to issue live invoices, the device must prove its technical competence by issuing test documents formatted in UBL 2.1 XML:

Statutory Safeguards & Rights Protection

Mandatory protections enforced by MHRSD & Saudi Labor Law

1
Standard Tax Invoice (B2B)Must pass cryptographic clearance validation with a calculated hash, digital signature, and UUID.
2
Standard Credit NoteMust reference an original invoice UUID and pass clearance checks.
3
Standard Debit NoteMust demonstrate upward adjustment compliance.
4
Simplified Tax Invoice (B2C)Must include compliant Base64 QR code and tamper-proof Invoice Counter Value (ICV).
5
Simplified Credit NoteMust reference original B2C transaction.
6
Simplified Debit NoteMust pass B2C reporting validation within the mandatory reporting schema.

Each sample invoice is submitted to the /compliance/invoices endpoint. ZATCA validates the XML against the official Schematron and business rule validation suite. If all test invoices return "status": "PASS", the EGS is officially certified for production promotion.

Promoting Compliance CSID to Production CSID

Once compliance tests are completed with zero validation errors, execute the final activation call:

HTTP Request:

http|Technical Specification / Reference
Verified Schema
PATCH /e-invoicing/core/production/csids HTTP/1.1
Host: gw-fatoora.zatca.gov.sa
Accept-Language: en
Accept-Version: V2
Content-Type: application/json
Authorization: Basic <Base64_Encoded(binarySecurityToken:secret)>

Request JSON Body:

json|Technical Specification / Reference
Verified Schema
{
  "compliance_request_id": "1029481"
}

Response (HTTP 200 OK):

json|Technical Specification / Reference
Verified Schema
{
  "requestID": 1029482,
  "dispositionMessage": "ISSUED",
  "binarySecurityToken": "MIIEzDCCA7SgAwIBAgIQX8...[PRODUCTION_X509_CERTIFICATE]...",
  "secret": "d8214fa7-109b-43ac-9321-f0923841bc19",
  "errors": null
}

Your EGS unit is now fully onboarded. Use this Production CSID and secret to sign live B2B invoices for real-time clearance and report B2C simplified invoices within the statutory 24-hour window.

Common Onboarding Errors & Troubleshooting

Error Code / MessageRoot CauseImmediate Remediation
`Invalid OTP / Expired`OTP exceeded the 60-minute validity window or was already consumed.Return to Fatoora Portal, revoke the stale request, and generate a fresh 6-digit OTP.
`Invalid CSR: Invalid OID`Missing or incorrectly structured custom ZATCA OID in the OpenSSL configuration.Ensure 1.3.6.1.4.1.311.20.2 and Subject Alternative Names contain the exact 15-digit VAT number.
`Compliance Incomplete (400)`Attempted to request Production CSID before passing all required test invoices.Run the full test suite (Standard & Simplified invoices + Credit/Debit notes) through /compliance/invoices.
`Authentication Failed (401)`Malformed Basic Auth header when promoting CSID.Verify that the string binarySecurityToken:secret is properly encoded into Base64 without trailing newlines.
`Curve mismatch (422)`Private key generated using RSA or NIST P-256 instead of secp256k1.Re-generate the private key using explicit OpenSSL curve command ecparam -name secp256k1.

Frequently Asked Questions (FAQ)

Can I use the same CSID across multiple POS cash registers?

No. Under ZATCA Phase 2 technical specifications, every physical device or independent EGS instance must have a unique serial number in its Common Name (CN) and maintain its own dedicated CSID. Sharing a single certificate across multiple retail registers violates tamper-proofing rules.

How long is a Production CSID certificate valid?

A ZATCA Production CSID is valid for 5 years from the date of issuance. However, if the company changes its commercial name, Tax Registration Number (TRN), or physical branch location, a new CSR must be generated and re-onboarded.

What is the difference between Simulation and Production onboarding?

Simulation onboarding uses sandbox endpoints (gw-fatoora.zatca.gov.sa/e-invoicing/simulation) to test integration without tax liability. Production onboarding connects directly to the live national tax engine (gw-fatoora.zatca.gov.sa/e-invoicing/core), generating legally binding tax records.

Can a taxpayer revoke an onboarded EGS device?

Yes. If an ERP server is decommissioned or a POS register is retired, the taxpayer can log into the Fatoora Portal, navigate to registered devices, and click Revoke Certificate to permanently disable that EGS unit's clearance permissions.

What happens if an invoice is signed with an expired Compliance CSID?

Compliance CSIDs cannot be used to sign live tax invoices. If submitted to the production clearance endpoint, ZATCA's API returns HTTP 401 Unauthorized with the error CERTIFICATE_NOT_AUTHORIZED_FOR_PRODUCTION.