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
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
The production certificate is issued and stored. The till is live.
The wizard remembers where you got to, so if you are interrupted you can pick it up rather than start again.
What happens on every sale afterwards
Once production onboarding is complete, 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.
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.
- 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.
- The system clock being wrong. Timestamps are signed. Keep the till’s date and time correct.
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.