ZATCA Phase 2 onboarding
Register the till with Fatoora, from generating the CSR to holding a production certificate.
Phase 2 is the integration stage. Your till has to be registered with ZATCA as a device, and every invoice has to be cryptographically signed and either cleared or reported through the Fatoora platform.
This needs the ZATCA Phase 2 licence module. The onboarding wizard in Settings does the technical work; your job is to supply accurate details and the one-time password.
Before you start
Have these ready:
- Your company details as ZATCA holds them: name, VAT number, commercial registration, address. They must match your ZATCA record, not merely resemble it.
- Access to the Fatoora portal, because you generate the OTP there.
- The branch and industry details for this specific till.
- Half an hour of quiet. Do it before opening, not during a rush.
Do this once per till. Each device gets its own keys and its own certificate.
Practise in simulation first
The wizard offers three environments: sandbox, simulation and production.
Run the whole thing in simulation before you touch production. Simulation behaves like the real platform, so you find out about a mistyped VAT number there rather than on the morning you go live. It costs you one extra run of a process you are about to do anyway.
The six steps
1. Seller details
Company name, VAT number, commercial registration and address. Copy them from your ZATCA registration rather than typing from memory — this is where most failed onboardings begin.
2. Environment and branch
Choose the environment, then enter the branch and industry details for this device. If you run more than one till, give each one details that identify it, so a rejected invoice can be traced back to a machine.
3. Generate the CSR
Review the CSR Config block first (the same csr.common.name / csr.serial.number / csr.organization.* fields as the ZATCA SDK). Then create the CSR.
The app creates a private key and a certificate signing request on the till itself.
The private key never leaves the machine. That is the point of the design, and it is also why a licence and a certificate are tied to one PC. It is also why your database backup matters: lose the machine without a backup and the device has to be onboarded again.
4. Compliance CSID
Log in to the Fatoora portal, generate a one-time password, and paste it into the wizard. The app exchanges the CSR for a compliance certificate.
The OTP is short-lived. Generate it when you are at this step, not before, or it will have expired by the time you use it.
5. Compliance sample invoices
ZATCA requires the device to prove it can produce correct documents. The app generates the required sample invoices, signs them and submits them automatically.
Nothing to do here but watch. If a sample is rejected, the error almost always points back to a seller detail from step 1 that does not match ZATCA’s record.
6. Production CSID
On simulation this is still a simulation device certificate, not a live filing. After the samples pass, Fatoora will not accept more simplified invoices on the compliance API — you must request this certificate before POS bills can be submitted.
On the production environment it is the live device certificate.
There is no way around this step. The compliance certificate from step 4 is rejected with a 401 on the reporting and clearance APIs, in simulation exactly as in production, so bills stay unsent until this certificate is on the till.
The wizard remembers where you got to, so if you are interrupted you can pick it up rather than start again.
Changing environment
Pick the environment in step 2 and generate a new CSR in step 3. That is the whole switch — there is no separate button for it.
Choosing a different environment and generating a new CSR retires the old onboarding: certificates are cleared and anything still queued for the previous gateway is dropped. Bills keep the environment they were signed for, so a simulation test bill can never be filed as a live tax invoice later. Those bills stay in the Documents list marked as belonging to the old environment.
What happens on every sale afterwards
Once the production CSID is on the till, each completed sale goes through this pipeline:
- A UBL 2.1 XML document is built for the invoice.
- It is signed with ECDSA using the device key, and the signature and certificate are embedded.
- The QR code is extended with tags 6 to 9 — XML hash, signature, public key and certificate stamp — on top of the five Phase 1 tags.
- A standard tax invoice is submitted for clearance, synchronously. It cannot be printed until ZATCA clears it.
- A simplified tax invoice is signed and queued for reporting, asynchronously.
In simulation (and sandbox), those same statuses still apply, but the till labels the bill Submitted (simulation) so it cannot be mistaken for a live Fatoora filing. The printed receipt carries the same banner.
Both the unsigned and the signed XML are stored against the document, and you can download the signed XML from the Documents screen whenever it is asked for.
Statuses and what to do about them
| Status | Meaning | Action |
|---|---|---|
| None | Phase 2 not active for this document | None |
| Pending | Signed, awaiting submission or response | Wait; retry if it sits there |
| Cleared | Standard tax invoice cleared by ZATCA | None. Safe to print |
| Reported | Simplified invoice reported successfully | None |
| Warning | Accepted, but with validation warnings | Read the warning; fix the cause |
| Failed | Rejected or unreachable | Investigate, then retry |
Filter the Documents screen by ZATCA status to see everything in one state at once.
When Fatoora is unreachable
Simplified invoices are reported after the fact, so a dropped connection does not stop you selling. Failures go into an outbox and are retried, and you can force a retry from the document.
Standard tax invoices are the exception, because clearance has to happen before issue. If the platform is down, those invoices wait. That is the rule of the scheme rather than a limit of the app, and it is a reason not to put a VAT number on a customer who does not actually need tax invoices.
Make a habit of checking
Once a week, filter Documents by ZATCA status failed and clear the list. A handful of stale failures is a small problem; a year of them is not.
Where things usually go wrong
- Seller details that do not exactly match the ZATCA record. By far the most common cause.
- Invalid-CSR on simulation (step 4). The app submits the CSR twice, once per certificate template, so this error means a field value is wrong rather than the format: the VAT must be the one the OTP was issued for, the taxpayer name must match the Fatoora record, and the commercial registration in the unit name must belong to that VAT.
- Invalid-CSR on production CSID (step 6). That POST sends only
{"compliance_request_id":"<id>"}as a string, not a CSR, so this is Fatoora refusing to promote the certificate it issued at step 4. Retrying the same request ID will not change the answer. Take a fresh OTP and run steps 4, 5 and 6 in one sitting. If it happens again, send the request ID and the VAT tosp_support@zatca.gov.sa; it has been reported on the simulation gateway for taxpayers who onboard normally in production. - NOT_COMPLIANT with
STATUS_INVALID_SIGNATUREat step 6. ZATCA’s certificate authority verifies the CSR’s own signature before it issues the certificate, and the compliance API does not. If you see this, the CSR on the till is unusable: generate a new one in step 3 and onboard again with a fresh OTP. - An expired OTP. Generate it at step 4, not in advance.
- The wrong environment. Onboarding in sandbox and expecting production certificates to work.
- A machine rebuilt without a backup. The device keys go with it and onboarding has to be repeated.
- A discounted sale rejected with BR-CO-15 / BR-32. Line discounts must not be sent as a document allowance. Retry the failed bill from Documents after this till has the fix; Fatoora will get a new XML with the VAT-inclusive total equal to net plus VAT.
Your responsibility
The app implements the technical specification. Your registration details, your tax rates and your filings remain yours. Validate in simulation before going live, and if you are unsure whether you are in scope, ask your accountant rather than guessing.