ZATCA E-Invoicing Guide (Saudi Arabia)

Overview

Saudi Arabia requires businesses registered for VAT to issue electronic invoices and connect their billing system directly to ZATCA (Zakat, Tax and Customs Authority) through the FATOORA platform. This is known as Phase 2 (Integration Phase).

QBM includes a built-in direct ZATCA integration. QBM builds the required XML invoice, signs it with your company's certificate, generates the QR code, sends it to ZATCA, and stores the result. No third-party middleware is required.

This guide covers the direct ZATCA integration only. It is different from the UAE PintAE e-invoicing module and from the older Accqrate middleware workflow. If your company is in the UAE, use the PintAE guide instead.

Read this first: ZATCA onboarding is a multi-stage process that involves your company's real tax identity and government credentials. Always complete Developer and Simulation testing before touching Production. Never share private keys, secrets, OTP values, or authorization headers by email, chat, or support tickets.

How QBM Works With ZATCA

When you submit a document, QBM performs these steps automatically:

Reads the saved invoice and builds the ZATCA UBL XML from your company data, customer data, and invoice lines.
Assigns the invoice identity: UUID, ICV (a counter that increases by one for every document), and PIH (the hash of the previous document, forming a tamper-evident chain).
Signs the XML using your certificate and private key, and embeds the ZATCA QR code.
Validates the document locally against the ZATCA rules.
Sends the document to ZATCA — standard invoices go to Clearance, simplified invoices go to Reporting.
Stores the result: the signed or cleared XML, the QR code, all identity values, the status, and the full ZATCA response.
Saves a copy of the document file to your archive folder.

Standard versus simplified

Type	Used for	ZATCA route	Timing rule
Standard (B2B)	Sales to another registered business; the buyer's details and VAT number are required.	Clearance — ZATCA validates and stamps the invoice before you give it to the buyer.	Must be cleared before it is shared with the buyer.
Simplified (B2C)	Retail and point-of-sale sales to consumers.	Reporting — you give the invoice to the customer immediately.	Must be reported to ZATCA within 24 hours.

QBM supports six document types: standard and simplified invoices, credit notes, and debit notes.

Not yet supported for ZATCA submission: advance/prepayment invoices, export invoices, self-billing, summary invoices, and foreign-currency invoices. If your business issues these, contact support before go-live.

The Full Journey at a Glance

Expect the complete process to span several days, mostly because of portal access and internal approval — not because of QBM.

Stage	What happens	Who
1. Prepare the company	Company tax data, customers, items, and accounts are completed in QBM.	Accountant / support
2. Configure settings	ZATCA is enabled, mode selected, archive folder set.	QBM administrator
3. Onboarding	CSR generated, compliance certificate obtained, compliance checks passed, production certificate obtained.	Administrator + taxpayer (for OTP)
4. Developer testing	Full rehearsal against the ZATCA sandbox using test identity. No real data submitted.	Support
5. Simulation testing	Full cycle against ZATCA's simulation environment using your real company identity.	Support + taxpayer
6. Production	Live activation and a single controlled smoke test, then normal operation.	Taxpayer + management approval

Golden rule: never skip a stage. Each environment issues its own certificate, and a certificate from one environment will never work in another.

Stage 1: Prepare the Company

ZATCA rejects invoices with incomplete seller or buyer data, so complete this before onboarding. QBM builds the seller block of every invoice from your company information, not from the CSR values.

Company information (required)

Path: Company > Company Information

Field	Requirement	Notes
Company Name	Required	The legal name. It appears as the seller name on every invoice.
Tax Registration Number (VAT)	Required — 15 digits	Must start with 3 and end with 3. QBM blocks submission if the format is wrong.
Registration Number (CRN)	Required	The commercial registration number. QBM sends it as the seller's additional identification. Submission is blocked if it is empty.
Address 1 (Street)	Required	Street name.
Address 2 (Building)	Required	Building number.
Address 3 (District)	Recommended	District or neighbourhood.
City	Required	For example, Riyadh.
Postal Code	Required	Five digits.
Country Code	Required — `SA`	The company country must be Saudi Arabia.
Base Currency	SAR	Foreign-currency invoices are not yet supported for ZATCA submission.

Accounts and tax setup (required)

Most common blocker: the message "Tax account must be specified if the tax amount is greater than zero" when saving an invoice. This means your VAT tax item has no liability account. Open the tax item used by your tax code and set its Liability Account to a VAT Payable account (an Other Current Liability). Without it, taxed invoices cannot be saved at all.

A VAT 15% tax code exists and is linked to a tax item.
The tax item has a Liability Account (for example, "VAT Payable").
A Discount Account exists if you give document-level discounts, otherwise discounted invoices cannot be saved.
Income and Accounts Receivable accounts are set up as usual.

Customers

Customer type	What is required
Business customer (standard invoices)	Name, VAT number, street, building, district, city, postal code, and country `SA`. Missing buyer data is the most frequent cause of rejected standard invoices.
Walk-in customer (simplified invoices)	A name is enough. Buyer details are not required for simplified documents.

Items

Each item must have a tax code so QBM can determine the VAT rate.
Enter item names in Arabic where possible — ZATCA expects the human-readable invoice to be in Arabic.
Zero-rated and exempt items require an official VATEX reason code. Contact support before selling such items through the ZATCA path.

Stage 2: Options > Integrations > Zatca

Tab Path: Options > Integrations > Zatca

This tab is available to administrators when the company country is Saudi Arabia.

Setting	What it does	What to do
Enable	Turns the direct ZATCA integration on and shows the Submit to Zatca button on sales documents.	Tick it before testing.
ZATCA Onboarding	Opens the onboarding dialog where certificates are obtained.	Used in Stage 3. This is the only place you get certificates.
Certificate Content	The production certificate (binary security token) received from ZATCA.	Do not type anything here. Onboarding fills it automatically. Shown masked for security.
Private Key Content	The private key that pairs with the certificate.	Filled by onboarding. Never share this value.
Authorization	The credential QBM uses to authenticate with ZATCA.	Filled by onboarding.
Mode: Developer / Simulation / Production	Selects the ZATCA environment. Changing it also switches the service addresses.	Start with Developer. Move to Simulation, then Production, only after each stage passes.
Reporting URL	The address used for simplified documents.	Leave the default for the selected mode unless support tells you otherwise.
Clearance URL	The address used for standard documents.	Leave the default for the selected mode.
Archive Folder	Where QBM saves a copy of every accepted document. Use Browse... to choose it.	Set a folder on a server or backed-up location. See Storage and Archiving.

Recommended: point the Archive Folder at a shared server path that is included in your nightly backup, for example \\server\QBM\ZatcaInvoices. ZATCA requires invoices to be retained for at least six years.

Changing mode: each environment needs its own onboarding. After switching mode you must repeat Stage 3 for that environment before you can submit.

Stage 3: Onboarding (CSR, CSID, Compliance)

Onboarding is how your QBM installation obtains its ZATCA identity. Click ZATCA Onboarding on the Zatca tab. The dialog has three tabs which you complete in order.

Do it in one sitting. The onboarding values are held in the dialog until you save them. Complete all three tabs and click the save buttons before closing.

Tab 1 — CSR (Certificate Signing Request)

A CSR is a request for a certificate. It contains your identity and produces a matching private key.

Check the Mode shown at the top matches the environment you are onboarding.
For Developer and Simulation the sandbox test identity is pre-filled. For Production the fields are deliberately blank — use Load Current Company to fill them from your company information, then correct anything that is wrong.
Click Generate CSR. The CSR and the private key appear in the two boxes.
Optionally click Save CSR... and Save Private Key... to keep secure copies.

CSR field	Meaning
Common Name	An identifying name for this billing unit.
Organization Identifier	Your 15-digit VAT number.
Organization Unit Name	Branch name. For VAT groups this must be the 10-digit TIN of the branch.
Organization Name	The company legal name.
Country Code	`SA`
Location	Branch address or location identifier.
Industry / Business Category	Your business activity, for example "Retail".
Serial parts 1, 2, 3	Identify the solution and unit. Keep the provided pattern.
Invoice Type bits	`1100` means this unit issues both standard and simplified documents.

Do not use the sandbox test identity for Production. Production onboarding must use your company's real legal name, real VAT number, and real address.

Tab 2 — Compliance

Obtain the OTP. In Developer mode any dummy value works (use 123345). In Simulation and Production the taxpayer must generate a real OTP from the FATOORA portal — it expires quickly, so have QBM ready first.
Paste the OTP and click Request Compliance CSID. The compliance certificate, secret, and request ID appear.
Click Run Compliance Checks. QBM generates, signs, and submits six sample documents built from your own company data — standard and simplified invoice, credit note, and debit note. Each result is listed separately.
When all six pass, click Apply Compliance Settings.

Why six samples matter: ZATCA requires proof that your system can produce every document type your certificate declares. QBM only marks compliance as passed when all six succeed — this protects you from being rejected later at the production step.

If a sample fails, the message tells you which one and why. It is almost always missing company or tax data. Fix it (see Stage 1) and click Run Compliance Checks again.

Tab 3 — Production

The compliance request ID, certificate, and secret carry over automatically.
Click Request Production CSID. This button is blocked until the compliance checks have passed for the same request and mode.
The production certificate, secret, and authorization preview appear.
Click Save Production Settings. QBM stores the credentials, enables ZATCA, and sets the service addresses for the selected mode.

Close the dialog and reopen Options > Integrations > Zatca. Certificate, Private Key, and Authorization are now filled (masked). QBM is ready to submit in that environment.

Stage 4: Testing in Developer (Sandbox)

The Developer environment is ZATCA's public sandbox. It is for rehearsal only: nothing submitted there is a real tax document. Use a dedicated test company, never a live one.

Useful ZATCA links

Purpose	Address
Sandbox / Developer Portal	`https://sandbox.zatca.gov.sa/`
E-invoice specifications	`https://zatca.gov.sa/en/E-Invoicing/SystemsDevelopers/`
Web validator (check an XML file)	`https://sandbox.zatca.gov.sa/Compliance`

Test company values

Create a new company and enter these values so they match the sandbox test identity:

Field	Value
Company Name	Maximum Speed Tech Supply LTD
Tax Registration Number	399999999900003
Registration Number	1010010000
Address 1 / 2 / 3	RRRD2929 / 2929 / Riyadh Branch
City / Postal Code	Riyadh / 12345
Country Code / Currency	SA / SAR

Step-by-step test run

Create the test company and enter the company information above.
Create master data: a VAT 15% tax code with a liability account, a few items, one business customer with a VAT number and full address, and one walk-in customer.
Open Options > Integrations > Zatca. Tick Enable, choose Developer, leave the URLs as they are, set the Archive Folder, and save.
Run onboarding (Stage 3) using OTP 123345. Confirm all six compliance checks pass and that you saved the production settings.
Test a standard invoice: create an invoice for the business customer with one or two taxed lines, save it, click Submit to Zatca, choose Standard Tax Invoice, and submit. Expect a cleared result and a QR code.
Test a simplified invoice: create a sales receipt for the walk-in customer, save, submit as Simplified Tax Invoice. Expect a reported result.
Test a credit note: create a refund or credit document that references the original invoice number and states a reason, then submit as Credit Note.
Test discounts: repeat with a line discount and a document discount to confirm totals are accepted.
Test failure handling: temporarily remove the company postal code, try to submit, and confirm you get a clear message. Restore the value afterwards.
Test the duplicate guard: reopen a submitted invoice and press Submit again. QBM should say it was already sent and show the stored result.
Check storage: open the Archive Folder and confirm one XML file exists per accepted document. Use Export PDF/A-3 on one document and open the PDF.

Developer stage is passed when: onboarding completed, all six compliance checks passed, one standard invoice cleared, one simplified invoice reported, one credit note accepted, a failure produced a readable message, and files exist in the archive folder.

Stage 5: Testing in Simulation

Simulation is ZATCA's realistic rehearsal environment. It uses your real company identity and a real OTP, but the documents are still not live tax documents. This stage is mandatory before production.

Use a copy of the real company, or the real company with the mode set to Simulation. Make sure the company information is the taxpayer's genuine legal data.
In Options > Integrations > Zatca, select Simulation. The service addresses change automatically.
Open ZATCA Onboarding and repeat Stage 3 completely. On the CSR tab use Load Current Company so the CSR carries the real identity.
Ask the taxpayer to generate an OTP from the FATOORA portal and paste it immediately.
Request the Compliance CSID, run the six compliance checks, apply, then request and save the Production CSID for Simulation.
Submit at least one standard invoice, one simplified invoice, and one credit note using realistic customer and item data.
Verify the archive folder and export one PDF/A-3 copy.
Collect evidence: screenshots of onboarding success, compliance results, and each accepted document.

Do not proceed to Production until the full Simulation cycle passes and internal approval is recorded. ZATCA states clearly that acceptance in a test environment is not approval of your system.

Stage 6: Going Live in Production

Production issues real tax documents. Everything submitted here is legally binding.

Confirm Simulation passed and management has approved go-live.
Confirm the taxpayer has completed e-invoicing registration on the FATOORA portal using their own taxpayer (ERAD) credentials.
In Options > Integrations > Zatca, select Production.
Open ZATCA Onboarding. On the CSR tab the identity fields are blank by design — click Load Current Company and verify every value is the real one.
Generate the CSR, obtain a fresh OTP from the FATOORA portal, and request the Compliance CSID.
Run the six compliance checks, apply the compliance settings, then request and save the Production CSID.
Smoke test: issue exactly one low-value real invoice and submit it. Confirm it is accepted and stored.
Only after the smoke test succeeds, begin normal daily invoicing.

Never mass-post as the first production action. One controlled document first, verified end to end, then normal operation.

Daily Use: Submitting Documents

Create and save the invoice, sales receipt, refund, or credit document as usual. The document must be saved and unmodified before it can be submitted.
Click Submit to Zatca on the toolbar.
Select the correct document type from the list.
Review the preview data, then click Submit.
Read the result. On success the QR code appears and QBM confirms where the document was archived.

Result	Meaning	Action
Cleared	A standard invoice was validated and stamped by ZATCA.	Give the buyer the cleared version.
Reported	A simplified invoice was accepted for reporting.	Nothing further needed.
Accepted with warnings	Accepted, but ZATCA noted data-quality issues.	Valid, but review the warnings and improve master data.
Rejected	ZATCA refused the document.	Read the error, correct the data, and submit again.
Submission failed	The document did not reach ZATCA — usually a connection problem.	Check the internet connection; simplified documents retry automatically.

Credit and debit notes must reference the original invoice number and state a reason for the adjustment. QBM blocks submission if either is missing.

Standard invoices: the version you give the buyer must be the one ZATCA cleared. Do not print and send a standard invoice before it shows a cleared result.

Storage, Archiving, and PDF/A-3

ZATCA requires every e-invoice and note to be kept, unaltered, for at least six years. QBM stores each document in three ways.

Where	What is kept
Company database	The authoritative record: signed or cleared XML, QR code, UUID, ICV, previous hash, current hash, status, document type, and the full ZATCA response for every attempt. QBM never deletes these records.
Archive folder	A copy of the document file, named in the standard ZATCA format, saved automatically on every accepted submission.
PDF/A-3 export	A human-readable PDF with the signed XML embedded inside it — the long-term archival format, produced on demand.

How the archive folder behaves

Saving is mandatory and automatic. There is no option to skip it.
The administrator sets the location in Options > Integrations > Zatca > Archive Folder.
If no folder has been set, QBM asks once when the submit dialog opens and remembers the choice.
After each successful submission QBM confirms the saved file location.
If saving fails — for example the folder was deleted or is not reachable — QBM warns immediately and opens a save dialog so you can store the file straight away. The folder you choose becomes the new archive location. The submission itself is not undone, because ZATCA has already accepted the document.

Exporting PDF/A-3

Open the submitted document and click Submit to Zatca.
Click Export PDF/A-3 and choose where to save.
The PDF contains the readable invoice, the ZATCA QR code, and the signed XML embedded as an attachment.

Backups: include both the company database and the archive folder in your backup routine, and keep those backups for the full retention period. QBM stores the data; retention is a business process.

Failed Submissions and the 24-Hour Rule

Simplified invoices must reach ZATCA within 24 hours of being issued. QBM helps you meet this automatically.

If a simplified document fails to reach ZATCA, QBM retries it every 10 minutes for up to 24 hours while QBM is open.
Standard documents are not retried automatically, because clearance must complete before the invoice is given to the buyer. Resubmit them manually once the problem is fixed.
Every attempt — successful or not — is stored with the full ZATCA response.

Keep QBM running on the machine that posts invoices, especially at the end of the day. If documents are still failing as the 24-hour deadline approaches, fix the cause immediately and resubmit manually.

Certificate (CSID) Renewal

ZATCA certificates expire (typically after about three years). An expired certificate stops all submission.

Note the expiry date at go-live and set a reminder at least one month before.
To renew, repeat the onboarding process: open ZATCA Onboarding, generate a new CSR, obtain a fresh OTP from the FATOORA portal, request the Compliance CSID, run the compliance checks, then request and save the new Production CSID.
Submit one document afterwards to confirm the new credentials work.

Renewal also applies if the billing unit changes significantly — for example a new branch, a new device, or a change of legal identity.

Compliance Responsibilities

QBM handles the technical requirements. These remain the responsibility of the business:

Issue every taxable sale through QBM — no off-system invoices.
Give buyers of standard invoices the ZATCA-cleared version only.
Make sure simplified invoices are reported within 24 hours.
Enter item and company names in Arabic so the printed invoice meets the language requirement.
Back up the database and the archive folder, and keep them for at least six years.
Renew the certificate before it expires.
Never delete or edit ZATCA records directly in the database — the invoice chain is tamper-evident and any gap is visible to ZATCA.
Keep the computer clock accurate; invoice timestamps are part of the signed data.

Troubleshooting

Message or symptom	Cause	Fix
Tax account must be specified if the tax amount is greater than zero	The VAT tax item has no liability account.	Set a VAT Payable liability account on the tax item used by your tax code.
Discount account must be specified	A discount was entered without a discount account.	Set a discount account on the document, or remove the discount.
Supplier registration number is required	Company Registration Number (CRN) is empty.	Enter the commercial registration number in Company Information.
Supplier VAT number format is invalid	The VAT number is not 15 digits starting and ending with 3.	Correct the Tax Registration Number.
Buyer information is missing for a standard document	The customer record lacks name, VAT number, or address.	Complete the customer record, or submit as a simplified document if it is a consumer sale.
Billing reference is missing for the credit/debit note	The note does not reference the original invoice.	Enter the original invoice number in the document's reference field.
Instruction note is missing	No reason was given for the credit or debit note.	Enter the adjustment reason in the description field.
Compliance checks required before production credentials	You tried to request a Production CSID before all six samples passed.	Run the compliance checks and make sure all six succeed.
Submit to Zatca button not visible	ZATCA is not enabled, or the document type does not support submission.	Enable ZATCA in Options and use a supported sales document.
Authentication or authorization failure	Wrong environment, or credentials from a different environment.	Confirm the mode matches the certificate. Re-run onboarding for that environment.
Invoice already sent to ZATCA	The duplicate guard is preventing a second submission.	This is correct behaviour. Use a credit note to correct an accepted invoice.
Another submission is in progress	Another workstation is submitting at the same moment.	Wait a few seconds and try again. The invoice chain must be built one document at a time.
Document could not be saved to the archive folder	The folder is missing, full, or not reachable.	Use the save dialog QBM offers, then correct the Archive Folder setting.

When escalating to support, include the company name, QBM version, ZATCA mode, the document number, and a screenshot of the message. Never include private keys, secrets, OTP values, or the full authorization header.