The ZATCA Setup Wizard
The setup wizard walks through the four things ZATCA needs before you can clear or report anything: who you are, the cryptographic identity you will sign with, the onboarding that registers it, and how the ERP should behave afterwards. Each step saves as you go, so it can be done over more than one sitting.
Step 1 — Company Information
Your details as ZATCA holds them. They must match the Fatoora portal exactly; a mismatch here is the commonest cause of an onboarding that will not go through.
| Field | Notes |
|---|---|
| VAT/TIN Number | Your VAT registration. |
| Company Name | As registered. |
| Commercial Registration (CRN) | Your CR number. |
| Business Category / Industry | What you do. |
| Branch / Unit Name | The unit this device or branch is registered as. |
Seller National Address
Required on every e-invoice, and required in the certificate request:
| Field | Notes |
|---|---|
| Building Number | The 4-digit building number from your national address. |
| Street Name / District / City | As on the national address. |
| Postal Code | 5 digits. |
| Additional / Plot No | Where you have one. |
The address is carried into the certificate signing request. A CSR generated without it is accepted by nothing downstream, which is why the request is regenerated at onboarding rather than reused — a stale or addressless CSR would otherwise strand the whole setup.
Step 2 — Certificate Generation
Your private key and the certificate signing request built from it.
| Option | Use when |
|---|---|
| Generate New Private Key | First-time setup. The usual choice. |
| Use Existing Private Key | You are migrating and already hold the key ZATCA knows. |
Generate CSR builds the request; Download CSR saves a copy. VAT number and company name must be filled in before the key can be generated — the screen says so rather than producing a request that would fail later.
Where the company name is in Arabic, the certificate subject still carries a non-blank Latin name. Some of the fields in a certificate cannot hold Arabic, and a blank one produces a request ZATCA rejects without explaining why.
Step 3 — ZATCA Onboarding
Registers your CSR with ZATCA and receives the compliance certificate.
| Field | Notes |
|---|---|
| OTP from ZATCA Portal | Generated in the Fatoora portal, and short-lived. Get it immediately before submitting. |
| Submit for Onboarding | Sends the request. Success returns the Compliance CSID. |
The CSR is regenerated at this point from your current company information, so an address added after the first attempt is included without you having to redo step 2.
When onboarding fails, the screen shows the real error from ZATCA rather than a generic message — an invalid OTP and an invalid CSR are different problems with different fixes, and being told which one it is saves a great deal of time.
Step 4 — Final Settings
How the ERP should behave from now on. See Settings for what each option does. This step also offers Request Production CSID.
The Production CSID
The production CSID is requested from the gateway of the environment you are currently in. That has a consequence worth understanding:
| Environment | What a Production CSID means |
|---|---|
| Production | You are going live. Real invoices will be cleared and reported. |
| Sandbox or Simulation | A test-environment credential. It does not move you to real production. |
The wizard's wording follows the environment, so it does not tell you that you are going live when you are not.
ZATCA issues the production CSID only after your compliance samples were actually accepted — see The compliance check.
Starting again
Clear Configuration resets the setup. It clears the request ids along with everything else, so a fresh attempt is genuinely fresh rather than half-carrying state from the failed one.