Blog/Engineering
Engineering

ZATCA Fatoora Onboarding, Step by Step: CSR, OTP, Compliance and Production CSID

D
DanteNov 21, 2026 · 6 min read
iFynx diagram: the 7 steps to onboard a device to ZATCA Fatoora, from key pair to production CSID

STEP-BY-STEP · CHECKED 21 NOVEMBER 2026

Onboarding a device to ZATCA Fatoora takes 7 steps: create a key, build a CSR, get a 1-hour OTP from the Fatoora portal, request a compliance CSID, pass the compliance checks, request the production CSID, then go live.

Each POS, ERP or app instance that issues invoices (an EGS unit) is onboarded on its own. We ran this flow end to end on ZATCA’s sandbox for our live Phase 2 demo; here is the order, the fields that matter and the mistakes that cost teams days.

iFynx diagram: the 7 steps to onboard an EGS unit to ZATCA Fatoora, from key pair to production CSID
The onboarding flow, from key pair to live invoices. Graphic: iFynx.

Integration with Fatoora sounds heavy, but most of it is one careful setup per device, done once. At iFynx we built a working ZATCA Phase 2 demo and passed ZATCA’s sandbox checks, so this guide follows what actually happened, not a brochure.

Three environments, three template names

ZATCA gives you three places to onboard. Start in the sandbox, rehearse in simulation, then go to production. The template name inside the CSR tells ZATCA which one you mean.

Environment Who it is for Where the OTP comes from CSR template
Sandbox (Developer Portal) Developers testing code Fixed test OTP (123345 in our tests) TSTZATCA-Code-Signing
Simulation Rehearsal with your real VAT number From the Fatoora Simulation portal PREZATCA-Code-Signing
Production Live invoices From the Fatoora portal, valid 1 hour ZATCA-Code-Signing

The 7 onboarding steps

From a new device to live invoices

1
Create a key pair on the unit. Each EGS unit (a POS terminal, an ERP instance, a cloud service) gets its own secp256k1 private key. The key never leaves the unit, and ZATCA never sees it.
2
Build the CSR. The certificate signing request carries the unit’s identity: a serial number in the form 1-solution|2-model|3-serial, your 15-digit VAT number, the invoice types the unit will issue (the 4-digit title, for example 1100 for standard and simplified), your address and business category, and the template name for the environment (table above).
3
Get an OTP from the Fatoora portal. Log in with your ZATCA (ERAD) account, choose onboard new solution unit/device, and enter how many OTP codes you need, one per unit. Each code is valid for 1 hour (Fatoora Portal User Manual), so generate it when the unit is ready.
4
Request the compliance CSID. The unit sends the CSR with the OTP to ZATCA’s compliance API. ZATCA returns a compliance certificate (binarySecurityToken), a secret and a request ID.
5
Pass the compliance checks. Using the compliance certificate, the unit signs and submits sample documents for each type it will issue: invoice, credit note and debit note, standard and/or simplified. ZATCA answers each with PASS, WARNING or ERROR. Our sandbox test write-up shows what each result looks like.
6
Request the production CSID. With the compliance request ID, the unit asks for its production certificate. From now on every invoice is signed with it.
7
Go live. Simplified (B2C) invoices are reported to ZATCA within 24 hours of issue. Standard (B2B) invoices are sent for clearance and shared with the buyer only after ZATCA clears them (E-invoicing Detailed Technical Guideline).

What a CSR looks like

This is the configuration behind the sandbox certificate in our demo. In production you change the template name, the VAT number and the serial number; the shape stays the same.

# csr.cnf (sandbox example, the one our demo uses)
[req_ext]
1.3.6.1.4.1.311.20.2 = ASN1:PRINTABLESTRING:TSTZATCA-Code-Signing
subjectAltName = dirName:dir_sect
[dir_sect]
SN = 1-iFynx|2-WebDemo|3-ed22f1d8-...   # solution | model | unit serial
UID = 399999999900003                    # VAT registration number
title = 0100                             # invoice types this unit issues
registeredAddress = Gaza
businessCategory = Software

openssl ecparam -name secp256k1 -genkey -noout -out key.pem
openssl req -new -sha256 -key key.pem -config csr.cnf -out unit.csr

Once the unit has its production CSID, every invoice is signed, hashed and chained to the one before it, and the QR code gains four extra fields. We decoded a real one in The 9 fields of a ZATCA QR code.

Mistakes that slow onboarding down

Check these before you generate OTPs

1
OTP expired. The code lasts 1 hour. Generate it after the unit is installed and ready, not the day before.
2
Wrong template name. A sandbox CSR (TSTZATCA) will not onboard in production. Keep one setting per environment.
3
Invoice types do not match. If the CSR says the unit issues only simplified invoices, do not submit standard samples, and the other way round.
4
Simulation is not production. Units onboarded in the Simulation portal are not carried over; onboard them again in production (user manual).
5
Lost private key. If a unit’s key is lost or the device is replaced, there is no recovery. Revoke the old unit in the portal (revocation cannot be undone) and onboard the new one.
6
One certificate for many tills. Each EGS unit needs its own OTP and CSID. Plan how many units you have before you generate OTPs.

Managing units after go-live

The Fatoora portal lists your onboarded solutions and devices, and lets you renew a unit’s CSID with a new OTP or revoke a unit you no longer use (Fatoora Portal User Manual). Keep an inventory of units, their serial numbers and where their keys live, so that replacing a till is a routine task and not an emergency.

How iFynx can help

iFynx connects POS, ERP, e-commerce and custom apps to ZATCA Fatoora, and handles onboarding for every unit.

  • Key generation, CSR and onboarding scripts for each environment.
  • Compliance checks with your real invoice samples, before the deadline.
  • Monitoring, renewal and revocation as your branches and devices change.

Try the live demo · Talk to iFynx · Estimate your project cost

Frequently asked questions

What is a CSID in ZATCA?

CSID stands for Cryptographic Stamp Identifier. It is the certificate ZATCA issues to one EGS unit so it can sign invoices. There is a compliance CSID for testing and a production CSID for live invoices.

How long is the Fatoora OTP valid?

One hour from when it is generated, according to ZATCA’s Fatoora Portal User Manual.

Do I need a separate CSID for each POS terminal?

Yes. Each EGS unit is onboarded on its own, with its own key, OTP and CSID.

Can I test onboarding without a real VAT number?

Yes, in the Developer Portal sandbox, with the test VAT number 399999999900003. That is how our live demo certificate was issued. Simulation uses your real VAT number.

What happens if I revoke a unit?

Its CSID stops working and the unit can no longer issue valid invoices. Revocation is not reversible; the device can only be onboarded again as a new unit.

Who has to do this, and by when?

Every taxpayer called in a Phase 2 wave. Wave 25 covers VAT-subject revenue above SAR 187,500 in any year from 2022 to 2025, with integration due by 1 February 2027 (ZATCA).

Related reading

Checked at 21 November 2026. Sources: ZATCA Fatoora Portal User Manual; ZATCA E-invoicing Detailed Technical Guideline; ZATCA Wave 25 announcement; our own sandbox onboarding.

🛡️ iFynx security bulletin · every SundayThe week’s vulnerabilities that matter to Gulf and Egypt companies, in one email

Every Sunday: the most serious confirmed CVEs and breaches, who is exposed in Saudi Arabia, the UAE and Egypt, and what to patch first. Free, in English and Arabic, one-click unsubscribe.

Read past issues →