CSR (Certificate Signing Request)
A CSR is the request a device sends ZATCA to get a CSID: it holds the secp256k1 public key plus the taxpayer and device fields ZATCA requires.
A CSR (Certificate Signing Request) is generated by the device together with a private key on the secp256k1 curve, and sent to ZATCA with the OTP to obtain a CSID. The private key never leaves you.
ZATCA reads specific fields from it: in the subject, C=SA, the branch in OU, the organisation in O and a name in CN. A certificateTemplateName extension (OID 1.3.6.1.4.1.311.20.2) holds ZATCA-Code-Signing for production and the developer portal, PREZATCA-Code-Signing for simulation. In subjectAltName: the serial SN, the VAT number UID, the functionality map title, the short address registeredAddress and the businessCategory.
What goes wrong: adding extensions such as basicConstraints or keyUsage makes the gateway answer Invalid-CSR. openssl silently drops any non-ASCII value in subjectAltName and every entry after it, so an Arabic address costs two fields and also ends in Invalid-CSR. The wrong template for the environment fails too.
Matheel generates the key and CSR for each device itself, matching the CSR the ZATCA SDK produces, and generates a fresh one at renewal.
Example
[ v3_req ]
certificateTemplateName = ASN1:PRINTABLESTRING:ZATCA-Code-Signing
subjectAltName = dirName:alt_names
[ alt_names ]
SN = 1-Matheel|2-…|3-…
UID = 3…3
title = 1100
registeredAddress = RRRD2929
businessCategory = General
FAQ
Why does the gateway answer Invalid-CSR?
Most often: extra extensions (keyUsage, basicConstraints), non-ASCII values inside subjectAltName, or a certificate template that does not match the environment.
Do I send my private key to ZATCA?
No. The CSR carries only the public key; the private key stays with the device to sign invoices.
Related terms
- CSID (Cryptographic Stamp Identifier)
- Compliance CSID
- EGS (E-invoice Generation Solution unit)
- OTP (Fatoora portal one-time password)
- ZATCA environments (developer portal, simulation, production)
Let Matheel handle this for you
Matheel signs the invoice, files it with ZATCA and keeps the counter and hash in one request, and returns the PDF with the QR.
Try Matheel, no signup Matheel API docs