Ritzy One • Saudi Arabia e-Invoicing

ZATCA e-Invoicing (Fatoora)

How Ritzy One clears and reports tax invoices and cash memos to ZATCA under Saudi Arabia's Phase-2 (Integration) e-invoicing mandate — onboarding a device, then automatically signing, QR-coding and submitting each Invoice, Cash Memo, Credit Note and Debit Note.

Saudi-Arabia companies only  |  Requires the ZATCA fatoora SDK on the server

1 How it works

When a document is finalized (Posted), Ritzy One builds a UBL 2.1 XML invoice, hands it to the ZATCA fatoora SDK for cryptographic signing, QR code and hash, then submits it to the ZATCA gateway:

Post document→ Build XML→ Sign + QR + hash (fatoora)→ Clearance / Reporting→ Store status + QR

Covered documents: Invoice Cash Memo Credit Note Debit Note — from both the Shipping billing screens and the Accounts transactions.

Invoice chain
Every submission carries an incrementing counter (ICV) and the previous invoice's hash (PIH). Ritzy One maintains this chain automatically and serializes submissions so the chain never has a gap.

2 Prerequisites

3 ZATCA settings

Open Tools → System Settings → ZATCA e-Invoicing. Set:

FieldMeaning
API EnvironmentDeveloper Portal (sandbox), Simulation, or Production. Onboard and test in a lower environment before Production.
Enable e-invoicingWhen on, posted documents are submitted automatically. Turn on only after onboarding succeeds.
Fatoora SDK homeFolder containing fatoora.bat. Blank uses the FATOORA_HOME environment variable.
CSR detailsCommon Name, Serial (SN), VAT/Org identifier, Org Unit/Name, Country, Invoice Type, Location, Business Category — used to generate the certificate request.

The right-hand panel shows certificate status (Compliance / Production CSID installed) and the current invoice-chain state (ICV and PIH).

4 Onboarding wizard

From ZATCA settings choose Onboarding Wizard. The steps mirror ZATCA's device onboarding:

  1. Generate CSR — creates the private key and certificate request from your CSR details.
  2. Compliance CSID — enter the portal OTP (sandbox default 123345) to receive a Compliance CSID.
  3. Compliance Tests — enter sample Invoice / Credit Note / Debit Note voucher numbers. The wizard submits each as Standard and Simplified; all must PASS.
  4. Production CSID — obtains the production certificate used for live submissions.
One device per install
The certificate is stored at the server's fatoora certificate folder, so one ZATCA-enabled company per install is supported. After success, return to ZATCA settings and turn on Enable e-invoicing.

5 Day-to-day use

Once enabled, nothing extra is needed: create and Post an Invoice, Cash Memo, Credit Note or Debit Note as usual. On posting, Ritzy One submits it to ZATCA and shows a status tag next to the document:

Click the QR button to view the ZATCA QR code for the cleared/reported document. A ZATCA failure never blocks the document itself — it saves normally and can be re-submitted.

6 Submissions log & retry

ZATCA settings → Submissions Log lists every clearance/reporting attempt with its status, ICV, hash and ZATCA response. Open a row to inspect the signed XML, request and response, view the QR, and Retry any failure after fixing the underlying data or configuration.

7 Troubleshooting

SymptomFix
No ZATCA tab / statusCompany Country isn't SAUDI ARABIA, or e-invoicing isn't enabled.
“fatoora.bat not found”Set FATOORA_HOME (env var or the settings field) to the SDK folder.
“Production credentials not configured”Complete the onboarding wizard to obtain a Production CSID.
Missing mandatory fieldsFill the customer's Building No, Address, City, Postal Code (and VAT No for Standard invoices).
Compliance test FAILOpen the message on the failing row; usually a missing customer/company field. Fix and re-run.
Chain integrity
Do not restore an old database copy over a live ZATCA install — the ICV counter and previous-hash (PIH) would regress and ZATCA would reject subsequent invoices.