Skip to content
E-invoicing in Saudi Arabia (FATOORA)

Onboarding a device and its CSID

How an invoicing device obtains its stamping certificate from ZATCA: key, certificate request, OTP, compliance checks, then the production certificate.

The certificate (CSID; the controls call it the cryptographic stamp identifier) ties an invoicing device to the taxpayer's VAT number. It starts in the FATOORA portal, where the taxpayer generates an OTP (up to 100 per request, each valid for an hour; there is no API for OTPs).

The device generates a key pair and a PKCS#10 request carrying the unit's common name, a serial number in the form "1-manufacturer|2-model|3-serial", the VAT number, branch name, taxpayer name, country, a four-digit invoice-type map (1100 = standard and simplified), location and industry. Sent with the OTP, it returns a compliance certificate.

With the compliance certificate the device submits sample documents for checking; the technical guidelines list three per type (invoice, debit note, credit note). When they pass, it requests the production certificate with the compliance request ID and uses it for stamping and reporting from then on. The certificate is valid for up to 60 months; renewal needs a new OTP and a new key.

The controls require the signing key to be marked non-exportable, or the disk encrypted when software stores it; moving the key to another device is a prohibited function.

In JooDax

Partly built

Onboarding is built: the programs generate the key and CSR themselves, request the compliance certificate, check one sample document (a simplified invoice), then request the production certificate, which has succeeded in the developer sandbox. But they request invoice type 1100 (standard and simplified) although standard invoices are not built, and check one sample instead of three per type; this has not been tried in simulation or production, where the platform may refuse the production certificate until the checks are complete. The CSR fields follow ZATCA's sample configuration (SN, UID, title in the alternative name) rather than the Security standard's table (organizationIdentifier). Renewal is not built. The key is kept inside the encrypted data file.

crates/jdx-einvoice-sa/src/unit.rs

Steps

  1. Generate an OTP in the FATOORA portal.
  2. Generate a private key and a CSR with the target environment's template on the device.
  3. Send the CSR and OTP to /compliance to get a compliance certificate and secret.
  4. Send signed sample documents to /compliance/invoices until they pass.
  5. Send the compliance request ID to /production/csids to get the production certificate.

Questions and answers

Does a developer-portal certificate work in production?

No. Developer-portal certificates are for testing only and do not work in the live environment.

What happens to a taxpayer's certificates on joining a VAT group?

They are revoked automatically, and devices must be onboarded again under the group number.

Related pages

Related concepts

E-invoicing in Saudi Arabia (FATOORA)

Sources

  1. Security Features Implementation Standards to the E-Invoicing resolution dated 2023-05-19 (v1.2) — ZATCA
  2. E-invoicing Detailed Technical Guidelines (vVersion 2) — ZATCA
  3. Developer Portal Manual (vVersion 3) — ZATCA
  4. FATOORA Portal User Manual (vVersion 3) — ZATCA
  5. Integration Sandbox API pages (Swagger): reporting, clearance, compliance, production CSID, renewal (ve-Invoicing Sandbox Release 2.1.0 (page lists 2.1.1 as latest)) — ZATCA
  6. الضوابط والمتطلبات والمواصفات الفنية والقواعد الإجرائية اللازمة لتنفيذ أحكام لائحة الفوترة الإلكترونية (قرار المحافظ رقم 62738 وتاريخ 1443/11/23هـ) (vfile dated 20230519 (decision 62738)) — ZATCA

Checked on: 4 November 2026. What concerns JooDax is taken from the programs’ own code.