ZATCA Sandbox Submission — Step by Step

Who This Guide Is For

Use this guide when you need to prove that QBM can build, sign, and submit e-invoices to ZATCA before any real company goes live. It is written for the person doing the testing, not for the end customer.

Before You Begin

Set aside roughly one to two hours for a first full run. Confirm each of these first:

• A dedicated test company. Never run sandbox testing against a live customer database.
• Administrator access in QBM. The Zatca options tab and onboarding are admin-only.
• Internet access. QBM must reach the ZATCA gateway over HTTPS. Confirm no proxy or firewall blocks it.
• A secure folder for the archive and for saved CSR and private-key files.
• Sandbox portal access (optional but useful) for the online validator and documentation.

Part A: Create the Test Company

QBM builds the seller block of every e-invoice from company information, so this data decides whether ZATCA accepts your documents.

1. Create a new company. Give it a clearly disposable name such as ZatcaSandboxTest so nobody mistakes it for production.
2. Open Company Information and enter the sandbox test identity below exactly as shown.
3. Save, then close and reopen the company so the values are loaded everywhere.

Part B: Create Master Data

You need enough master data to raise a taxed invoice. Two items and two customers are sufficient.

B1 — Accounts and tax

1. Create the accounts you will need: a sales income account, an accounts receivable account, and a VAT Payable account of type Other Current Liability. Add a discount account too if you plan to test discounts.
2. Create a VAT 15% tax code linked to a tax item.
3. Open the tax item and set its Liability Account to the VAT Payable account you just created.

B2 — Items

1. Create at least two items with a unit price and the VAT 15% tax code assigned.
2. Use Arabic names where possible so the printed document reflects a realistic Saudi invoice.

B3 — Customers

1. Create a business customer for standard invoices, with the full detail below. Incomplete buyer data is the most frequent reason a standard invoice is rejected.
   • Name, for example ACME VAT Customer
   • VAT number, for example 399999999800003
   • Street, building number, district, city, postal code
   • Country code SA
2. Create a walk-in customer for simplified invoices. A name is enough; buyer details are not required for consumer sales.

Part C: Enable ZATCA (Developer)

Path: Options > Integrations > Zatca

1. Tick Enable. This turns on the integration and makes the Submit to Zatca toolbar button appear on sales documents.
2. Select Mode = Developer. The Reporting URL and Clearance URL switch automatically to the sandbox addresses. Leave them exactly as they are.
3. Set the Archive Folder using Browse…. Choose a folder you can inspect later, because you will verify the saved files in Part H.
4. Leave Certificate Content, Private Key Content, and Authorization empty. Onboarding fills them in Part D. Typing values here by hand is never correct.
5. Save the options.

Part D: Run Onboarding

Onboarding obtains the certificate QBM signs with. Complete all three tabs in one sitting — the values live in the dialog until you save them.

Path: Options > Integrations > Zatca > ZATCA Onboarding

D1 — CSR tab

1. Confirm the Mode shown in the dialog is Developer.
2. The sandbox identity is pre-filled for non-production modes. Leave it as is for your first run.
3. Click Generate CSR. The CSR and the private key appear in the two boxes.
4. Click Save CSR… and Save Private Key… and store both in your secure test folder.

D2 — Compliance tab

1. In OTP, enter 123345. The Developer environment accepts a dummy OTP; a real portal OTP is only needed in Simulation and Production.
2. Click Request Compliance CSID. You should receive a compliance certificate, a secret, and a request ID.
3. Click Run Compliance Checks. QBM builds, signs, and submits six sample documents from your own company data and lists a result for each.
   • Simplified invoice, simplified credit note, simplified debit note
   • Standard invoice, standard credit note, standard debit note
4. When all six pass, click Apply Compliance Settings.

D3 — Production tab

1. The request ID, compliance certificate, and secret carry over automatically.
2. Click Request Production CSID. This button stays blocked until all six compliance checks have passed for the same request and mode — that gate is deliberate.
3. Click Save Production Settings.
4. Close the dialog, reopen Options > Integrations > Zatca, and confirm Certificate Content, Private Key Content, and Authorization are now populated and masked.

Part E: Submit a Standard Invoice

This is the core test: a business-to-business invoice that must be cleared by ZATCA before it could be given to a buyer.

1. Create a customer invoice for the business customer from Part B3.
   • Add one or two lines using the taxed items
   • Confirm VAT 15% is calculated on the lines
   • Check that the totals look correct
2. Save the invoice. The document must be saved and unmodified — if it is still being edited QBM asks you to save first.
3. Click Submit to Zatca on the toolbar.
4. Select the document type Standard Tax Invoice from the Type list. The preview data loads underneath.
5. Review the preview, then click Submit.
6. Read the result. On success the QR code appears in the results area and QBM confirms where the document was archived.

Part F: Submit a Simplified Invoice

A consumer sale that is reported to ZATCA rather than cleared.

1. Create a sales receipt or cash sale for the walk-in customer with one or two taxed lines.
2. Save the document.
3. Click Submit to Zatca.
4. Select Simplified Tax Invoice as the type.
5. Click Submit and confirm the status is Reported, or accepted with warnings.

Part G: Submit a Credit Note

Credit and debit notes carry extra requirements that are worth testing explicitly.

1. Create a refund or credit document against the invoice you submitted in Part E.
2. Enter the original invoice number in the document reference field. This becomes the billing reference and is mandatory.
3. Enter a reason in the description field, for example Goods returned by customer. This becomes the instruction note and is also mandatory.
4. Save, click Submit to Zatca, and select Standard Tax Credit Note.
5. Click Submit and confirm the document is accepted.

If the customer uses debit notes, repeat the same sequence with an adjustment document and the Standard Tax Debit Note type.

Part H: Verify What Was Stored

Submission is only half the requirement — ZATCA also requires that documents are retained. Verify all three storage layers.

H1 — Inside QBM

1. Reopen one of the submitted invoices and click Submit to Zatca again.
2. QBM should report that the invoice was already sent and display the stored QR code, with the Submit button disabled.

H2 — The archive folder

1. Open the folder you configured in Part C.
2. Confirm there is one XML file per accepted document, named in the standard ZATCA format.
3. Open one file and confirm it is a complete signed UBL invoice.

H3 — PDF/A-3 export

1. Open a submitted document and click Submit to Zatca.
2. Click Export PDF/A-3 and save the file.
3. Open the PDF and confirm it shows the invoice, the totals, and the QR code, and that the signed XML is attached inside the PDF.

Part I: Negative Tests

A passing integration must also fail clearly. Run at least two of these and confirm the message is readable and no document is silently lost.

Part J: Sign-Off Evidence

Collect this before declaring the sandbox stage passed. It is also what support should attach to a rollout ticket.

• QBM version or build number, and the test database name
• Screenshot of Company Information showing the seller data
• Screenshot of Options > Integrations > Zatca with Developer mode selected and secrets masked
• Screenshot of onboarding showing the compliance CSID received
• Screenshot of all six compliance checks passing
• Screenshot of the production CSID response
• Standard invoice accepted, showing status and QR code
• Simplified invoice accepted, showing status and QR code
• Credit note accepted, with the original invoice number visible
• Archive folder listing showing one file per document
• One exported PDF/A-3 file
• At least one negative test showing a readable error

Troubleshooting

Related Guides

• ZATCA E-Invoicing Guide (Saudi Arabia) — the full reference covering every stage, settings, archiving, renewal, and compliance duties
• ZATCA Submission Guide for Customers — the day-to-day version written for end users
• QBM Options and Settings Guide
• Customer Invoices and Sales Receipts Guide
• Common Messages and Troubleshooting Guide