ZATCA onboarding fails or the OTP is rejected
Why a device cannot be onboarded or renewed with ZATCA, every message you may see, and how to fix it step by step.
You press Request, Run the checks, Get it or Renew in Settings → E-invoicing (ZATCA) and a red
message appears instead of the next step. ZATCA's own messages are listed under it as code: message. When an
onboarding step fails, the device shows Problem and the reason in red under its name.
Why it happens
Most failures come from one of these, the most common first:
- The OTP expired. An OTP from the Fatoora portal is valid for one hour after you generate it.
- The OTP was already used or mistyped. Each OTP onboards one device. A typo or a second use is refused.
- The OTP is for another environment. An OTP from the real Fatoora portal works only for a Production device; a Simulation device needs an OTP from the simulation portal; a Developer sandbox device uses ZATCA's developer test values.
- The VAT number does not match. The branch's VAT number goes into the certificate request. If it is not the VAT number of the Fatoora account the OTP came from, ZATCA refuses.
- The branch details are incomplete or wrong. The legal name, VAT number, registration and address must be complete before a device can be added and onboarded.
- The certificate ended or was revoked. A ready device whose certificate ended, or was revoked in the portal, can no longer sign in to ZATCA. When ZATCA refuses its credentials while sending, the device moves to Problem and stops signing: another ready device of the branch signs, or invoices wait.
- ZATCA could not be reached, for a short time or because of its maintenance.
What to do
- Generate a new OTP in the Fatoora portal (https://fatoora.zatca.gov.sa → Onboard new solution unit/device) and use it within the hour. Type the 6 digits and press Request again. The device keeps its place; nothing is lost.
- Check the environment on the device's label (Developer sandbox, Simulation or Production) and get the OTP from the matching portal. A device's environment cannot be changed: if it is wrong, Delete the device (while it is Not onboarded) and press Add a device with the right Environment.
- Check the VAT number in Settings → Branches: it must be exactly the 15-digit number of your Fatoora account (starts and ends with 3). Correct it, save, then use a new OTP.
- Complete the branch. If the panel shows Complete the branch first: …, open Branches from the link and fill in what it lists. Add a device works again once it is complete.
- Run the checks again if some show ✗. Read ZATCA's message next to each ✗; it usually names the missing or wrong seller detail. Correct the branch, then press Run again. Get it works only when every check passed.
- Renew the certificate when Renew soon shows, or when the device shows Problem after ZATCA refused its credentials: press Renew certificate, get an OTP in the portal under Renew existing cryptographic stamp identifier, type it and press Renew. A failed renewal leaves a ready device ready (only the error shows). If renewal keeps being refused, press Onboard again (it starts from a new OTP of Onboard new solution unit/device), or Revoke the device and onboard a new one.
- Wait and retry when ZATCA could not be reached. Invoices wait as ZATCA: Pending and are sent later by themselves.
Note
Invoices of a branch whose e-invoicing is still off (until its production device is ready) are not e-invoices and are never sent. When e-invoicing is on and no device is ready, invoices wait as ZATCA: Pending and are signed and sent in order as soon as a device is Ready.
Messages and fixes
| Message | Cause | Fix |
|---|---|---|
| The OTP must be the 6 digits from the Fatoora portal | The OTP is not six digits | Type only the six digits |
| ZATCA did not issue a compliance certificate (…) | ZATCA refused the OTP or the request (the device shows Problem). The number is ZATCA's answer code; no answer means ZATCA could not be reached | Use a new OTP, check the environment and the VAT number (steps 1 to 3), then Onboard |
| The branch details are not ready for a certificate request | Details the certificate needs are wrong; the lines under it say which, for example The VAT number must be 15 digits starting and ending with 3 | Correct the branch in Branches and try again |
| This branch is in a VAT group: enter the member's 10-digit TIN as the organisation unit | The VAT number belongs to a VAT group (its 11th digit is 1) and Organisation unit is empty or not 10 digits | Type the member's 10-digit TIN in Organisation unit when you add the device |
| For a VAT group the organisation unit must be the member's 10-digit TIN (under The branch details are not ready …) | The device was added without the member's TIN | Delete the device and add it again with Organisation unit filled |
| This device is already onboarded; use renewal | The device is Ready | Use Renew certificate instead |
| Request the compliance certificate first | The OTP step was not done | Do step 1 of the wizard first |
| Run the compliance checks first; all of them must pass | A check failed or was not run | Press Run again and fix what ✗ shows |
| ZATCA did not issue the production certificate (…) | ZATCA refused the last step (the device shows Problem) | Press Onboard, then Get it again later; if it keeps failing, add a new device with a new OTP |
| Only an onboarded device can be renewed | The device never had a production certificate | Finish onboarding with Onboard |
| ZATCA did not renew the certificate (…) | The renewal OTP was refused. A ready device stays ready | Get a new OTP under Renew existing cryptographic stamp identifier and press Renew again |
| ZATCA refused the device credentials (401) or (403) (under the device or on invoices) | The certificate ended or was revoked. The device shows Problem and stops signing | Renew certificate, or Onboard again with a new OTP, or Revoke it and onboard a new device |
| This branch is not in a country with ZATCA e-invoicing | The branch is not in Saudi Arabia | E-invoicing devices are only for Saudi branches |
| This device has signed e-invoices; revoke it instead of deleting it | A used device cannot be deleted | Use Revoke |
| Self-billing is not allowed on export invoices (BR-KSA-07) | Both Export invoices and Self-billed were switched on | Switch one of them off |
| The branch has no onboarded e-invoicing device yet / Waiting for an onboarded device | E-invoicing is on and the branch has no Ready device | Onboard a device; waiting invoices are then sent |
On the Arabic screen, these messages and the device errors show in Arabic. ZATCA's own lines stay as ZATCA wrote them, in the Language of ZATCA's messages chosen under Document options.
Related articles
- Set up ZATCA e-invoicing for a branchFrom the Saudi branch's seller details to onboarding a device with the OTP from the Fatoora portal and the first cleared or reported invoice.
- E-invoicing (ZATCA)See each Saudi branch's e-invoicing state, onboard and renew its devices with ZATCA, set document options and follow e-invoices that need attention.
- BranchesYour offices: each works by its country's currency, VAT and e-invoicing, and prints its own seller details on its invoices.
- Error messages: e-invoicing (ZATCA)Every message you may see when you set up ZATCA e-invoicing, send invoices to ZATCA or fix a rejected document, and what to do.