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 builtOnboarding 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
- Generate an OTP in the FATOORA portal.
- Generate a private key and a CSR with the target environment's template on the device.
- Send the CSR and OTP to /compliance to get a compliance certificate and secret.
- Send signed sample documents to /compliance/invoices until they pass.
- 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
- KSA-15 Cryptographic stamp
- BT-31 Seller VAT registration number
- BR-KSA-60 · The cryptographic stamp is mandatory on simplified documents and their notes.
Related concepts
- The e-invoice generation unit (EGS)The device or software that issues invoices and holds their chain, key and certificate; each unit has one sequence and one certificate.
- The cryptographic stamp (digital signature)An ECDSA signature in XAdES form over the document hash and signing properties, made with a registered device key and a ZATCA-issued certificate.
- Local test mode in the JooDax programsUntil the business onboards its device with ZATCA, the programs stamp documents with a self-signed certificate and print them with a QR code, sending nothing anywhere.
- Reporting simplified invoices within 24 hoursSending a simplified invoice or note, already stamped and handed to the buyer, to FATOORA within 24 hours of issue.
E-invoicing in Saudi Arabia (FATOORA)
Sources
- Security Features Implementation Standards to the E-Invoicing resolution dated 2023-05-19 (v1.2) — ZATCA
- E-invoicing Detailed Technical Guidelines (vVersion 2) — ZATCA
- Developer Portal Manual (vVersion 3) — ZATCA
- FATOORA Portal User Manual (vVersion 3) — ZATCA
- 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
- الضوابط والمتطلبات والمواصفات الفنية والقواعد الإجرائية اللازمة لتنفيذ أحكام لائحة الفوترة الإلكترونية (قرار المحافظ رقم 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.