ZATCA Compliance

Overview

Keeps invoices aligned with Saudi Arabian ZATCA e-invoicing rules, including digital signatures and QR codes.

Key concepts

Key terms, statuses, and records that appear in ZATCA Compliance in XFatora.

Setup & prerequisites

Connect required settings, templates, and defaults for ZATCA Compliance in XFatora.

Roles & permissions

Assign role-based access, approvals, and visibility for ZATCA Compliance in XFatora.

Main workflows

ZATCA Compliance module

ensures that your invoices meet the Saudi Arabian e-invoicing regulations mandated by the Zakat, Tax and Customs Authority (ZATCA). Saudi Arabias e-invoicing rules (often referred to as Phase 1 and Phase 2) require businesses to include a special QR code on invoices and, in Phase 2, to digitally sign invoices and clear them through ZATCAs system. This module helps automate QR code generation for Phase 1 and the more complex invoice signing and reporting for Phase 2, keeping you compliant with minimal manual effort.

Overview of ZATCA Phases

Phase 1 (Dec 2021, Generation):

All VAT-registered businesses in KSA must generate tax invoices electronically with specific fields and a QR code containing certain details (sellers name, VAT, timestamp, total, VAT total, etc.). These invoices should be tamper-evident (no deletion or modification without trace). However, Phase 1 did not require integration with ZATCAs systems it was mostly about format and storing invoices. The module ensures every invoice printed or emailed has a compliant QR code and required fields.

Phase 2 (starting 2023-2024, Integration):

Invoices must be digitally signed and cleared with ZATCA. This means your system should generate an invoice in a specific XML format (UBL with extensions), sign it with a cryptographic certificate, and send it to ZATCA in real-time (for clearance if its a B2B invoice, or reporting within 24 hours if B2C simplified invoice). ZATCA returns a cryptographic stamp (and an acknowledgment ID for clearance) that must be embedded in the invoice (for example, updating the QR code content). The module handles generating this UBL XML, signing it using your configured digital certificate, sending it via API to ZATCA, and capturing the response (success or errors, and the cleared invoice hash/ACK). It then stores evidence (signed XML, etc.) and ensures the invoices QR is updated with the required cryptographic stamp data.

Initial Setup for ZATCA Compliance

Obtain ZATCA Credentials:

For Phase 2 integration, you need to have onboarded with ZATCAs e-invoicing portal. This involves generating a cryptographic

Certificate Signing Request (CSR)

and obtaining a

device certificate (CSID)

from ZATCA. The module provides a place to input these. In

Compliance Settings

(likely under Modules > ZATCA Settings), there are fields for

CSR

,

CSID

, and the associated private key and certificate chain. The CSR and private key are generated by you (or the software) and submitted with an OTP on ZATCAs portal to get the CSID (a certificate ID). Once obtained, load the certificate and private key into the module settings. These are used to sign invoices digitally. Treat them securelythis is akin to your digital tax signature.

Environment Setting:

Decide if youre connecting to

Sandbox

or

Production

environment of ZATCA. In settings, the

Environment

(xf_zatca_env) can be set to sandbox or production. Start with sandbox to test, then switch to production when ready. Use the OTP onboarding process separately for production to get a production CSID.

Seller Info:

Fill out ZATCA-specific required fields like

Seller Name

(should exactly match whats on your VAT registration) and

VAT Number

in settings. These will populate the invoice XML. Ensure your companys address and VAT are also correctly set in the main company profile (the module might use those too).

Features Toggle:

The module settings allow enabling Phase 2 features (like digital signing and reporting). Option

xf_zatca_wave2_enabled

should be ON when youre ready for Phase 2 live. Before that, in Phase 1, you might only use QR code generation which the module did automatically once active. Phase 2 functionalities (XML generation, reporting to ZATCA) are more complex; only enable once certificate is configured. There might also be a

Phase selection

if needed (some companies may be in phase rollout). But likely, enabling wave2 covers it.

QR Code on Template (Phase 1):

In Phase 1, each simplified invoice (B2C) requires a QR code containing at least 5 fields encoded (seller name, VAT number, timestamp, total with VAT, VAT amount). The module automatically injected this into invoice PDFs by hooking into PDF generation. Ensure on invoice printouts the QR is appearing. The setting

Attach QR to PDF

(xf_zatca_attach_qr_pdf) should be enabled. Test by creating an invoice and viewing PDF a square QR code graphic with label ZATCA QR should be present. Scanning it with a generic QR reader will show encoded base64 data that ZATCAs app can decode into the fields. (It wont be human-readable as plain text; thats okay. ZATCA provides an app to verify it.)

Test Mode:

Use sandbox environment and perhaps a small test invoice to ensure connectivity. The module has functions to

Generate XML

without reporting, for testing. For example, clicking ZATCA XML on an invoice just generates and saves the XML file but doesnt send it. You can then inspect or validate that XML with ZATCA sandbox manually. Once confident, you try ZATCA Report or ZATCA Clear which actually calls the API.

Creating and Issuing Invoices under ZATCA Compliance

(We assume you have Phase 2 fully set up, as Phase 1 was mainly QR code which is automatic when issuing normal invoices.)

Invoice Creation:

Create invoices as usual in the system (fill buyer details, line items, VAT etc.). Make sure to include the customers VAT number if its a tax invoice to a VAT-registered business (for B2B, required). For a simplified invoice (B2C), a generic Consumer name is fine if you dont have buyer details, but you must still produce an e-invoice with QR. Save the invoice. At this point, if you preview or print it, the QR code is already embedded (with basic info, not the cryptographic stamp yet).

Generate and Clear/Report via ZATCA:

On the invoice admin page, youll see new buttons added by the module:

ZATCA XML

,

ZATCA Report

,

ZATCA Clear

,

ZATCA Send

. Use them accordingly:

ZATCA XML:

This generates the UBL XML for the invoice and digitally signs it, but does not send to ZATCA. It saves the signed XML on your server and marks the invoice status in the DB as xml_generated. Use this if you want to manually inspect or if its a B2C invoice that you plan to report in batch (though KSA requires near real-time for B2C too, but difference is B2C only needs reporting not clearance). After generating, the module inserts the invoices unique hash and your signature into the QR code and invoice record. You would then at least have a digitally signed invoice ready (the QR code is now enriched with cryptographic stamp).

ZATCA Report:

Use this for a

simplified invoice (B2C)

or if you want to just report an invoice without clearance. When clicked, the module composes the final invoice XML, signs it (if not already), base64-encodes it, and calls ZATCAs API for reporting. ZATCA will respond with HTTP status if success, invoice is reported. The module then marks it as reported (status reported) and stores the response (an ack or just status code). For B2C simplified invoices, no further ack ID is needed to put on invoice, but the law requires invoice to be sent to customer within 24h of generation with the stamp (which we have via signature). So after reporting, you can give the invoice to customer (it already has the cryptographic stamp via QR).

ZATCA Clear:

Use this for

standard tax invoices (B2B)

that require clearance. This process is similar but calls the clearance API. ZATCAs response if successful will include an

Acknowledgment ID (clearance certificate)

and likely ZATCAs own digital signature of the invoice. The module captures that and updates invoice status to cleared. It likely stores the clearance result (ACK and maybe updated XML) in the database and might update the QR or invoice to include evidence of clearance (like adding the ACK:<number> label in system or including ZATCAs stamp in the QR content). The code suggests it touches status and stores response, and the QR stored already had invoice hash and our signature; it might not necessarily embed ZATCA signature in QR (I dont think ZATCA requires that to be in QR, just in XML which we have). Now the invoice is cleared.

ZATCA Send:

This is a convenience that auto-determines whether to report or clear based on invoice type (B2C vs B2B). It uses detect_invoice_type (looks at whether customer has VAT or isCompany). If type is b2b, it does clearance; if b2c, it does report. This one-click is handy to ensure compliance without manually choosing. Use this on finalizing an invoice to do whatever is needed. You can override route for a specific invoice with a dropdown Always treat as B2B or B2C if needed (for example, if an invoice is to a registered person but you want to treat it as simplified for some reason) the modules panel allowed a

routing override

setting per invoice. Unless special cases, auto mode works.

Result:

After performing the appropriate action, the invoice in the system now has all required data: its digitally signed, and for B2B invoices, its cleared (so legally valid to use for VAT input claims, etc.). The QR code on the invoice contains: seller info, invoice timestamp, total, tax, plus now the cryptographic stamp (which is a base64 of the invoice hash, the signature, public key, and perhaps the serial number of device). A ZATCA inspection app can scan this QR and verify if it matches a reported invoice in their system (for B2C) or if its properly signed for B2B.

Providing Invoice to Customer:

Now you can deliver the invoice PDF to the customer via email or print, as usual. Make sure to do it only after clearance for B2B, since legally the invoice must include the cleared stamp from ZATCA before it's valid to send to buyer. For B2C, you must at least include your cryptographic stamp (which we did) and deliver within the mandated time. The customer, if B2B, can actually use ZATCAs portal to verify the invoice using the clearance ID or scanning QR they might be required to only book invoices that have that stamp. So ensure no step is missed.

Post-Issuance and Compliance Management

Handling Errors:

If ZATCAs API returns an error when trying to clear/report (common errors could be: clock out of sync, duplicate invoice number, formatting issues, or missing fields like buyer VAT), the module will show a warning (maybe in an alert or on the invoice panel itll show last response code). You must fix the issue and reattempt. E.g., if error says buyer ID invalid, correct the customer VAT format and try again. The module logs response in a table (xf_zatca_wave2_invoices) including error messages which it shows in a panel on invoice page (it prints errors if present). After fixing, you might click

Send

again. The module is idempotent with proper checks to avoid double sending the exact same invoice if already cleared (it keeps track via route override and statuses). But if its error, it likely lets you try until success.

Status Tracking:

On the invoice view for admin, the modules panel displays status (

xml_generated

,

reported

,

cleared

, or any failure codes). It also shows if any

Acknowledgment ID

was received (itll display ACK label if present) and any error messages if exist as an Errors preformatted text block. Use this to audit which invoices have completed compliance. Perhaps filter or report periodically to ensure all invoices have a final status.

Periodic Reporting (for B2C):

While B2B must be cleared before issuing, B2C simplified invoices must be reported within 24h. The modules

Send

can handle it immediately which is ideal (especially if you have continuous connection). If you ever issue offline (like internet down), the system still generates invoice and QR with your stamp, you give to customer, and you then need to report it once back online. Use the

Report

function on that invoice as soon as possible. The law mandates within 24h the module doesnt automatically remind you, so implement a process: perhaps daily ensure all yesterdays B2C invoices were sent. You could run a query on the status or see in ZATCA portal if any missing.

Credit/Debit Notes:

The module likely handles credit notes similarly (they are also e-invoices type). When issuing a credit note (negative invoice), it will treat it as an invoice in XML with proper type code (perhaps as negative amounts or a separate type). Ensure to clear/report those too via same actions.

Integration with Accounting:

When ZATCA module clears or reports, it doesnt alter accounting entries (the invoice was already recorded financially). But it adds assurance that the invoice is legit. When an invoice is canceled or edited, ZATCAs rules are that you cannot delete invoices. Youd issue a credit note or debit note to adjust. The module disables deletion of issued invoices by hooking into system (the code likely prevents deletion if active) in Phase 1, it was mandated that systems cant allow deletion of invoices; module might enforce that by removing delete option or at least logging all changes. Check that you cannot simply delete an invoice if you can, have a policy not to (for compliance). The modules

tamper detection

is somewhat manual but the audit trail can show if someone changed an invoice after generation. Ideally, once an invoice has QR or is cleared, lock it (the module does mark it as cleared and probably prevents editing content by design).

Audit and Archiving:

ZATCA requires you store invoices and related data for many years (at least 6). The module stores the signed XML (in uploads/xf_zatca/xml folder) and QR code images (in uploads/xf_zatca/qr). Ensure your backup routine includes these folders. Also, the database records have invoice hash, etc. If an auditor wants to verify, you should provide either the printed invoice with QR (they can scan to verify authenticity) or the XML with digital signature. Keep those safe. Also, the private key used for signing must remain secure rotate it if needed but maintain ability to verify old invoices (thats what the certificate chain is for).

Updating Certificates:

ZATCA device certificates expire (I recall maybe every 1-2 years). Mark when yours expires. Before that, youll need to generate a new CSR and update the module with new cert and key. The modules onboarding function

onboard_with_otp

helps registering a new CSID using OTP they have separate calls to production and sandbox. Use the

Onboard

button in settings with a fresh OTP each time you add a new device or renew. The module can handle multiple in sequence (it just stores current cert and key though). If renewing, do so a bit early to avoid downtime.

Periodic Updates:

Keep the module updated as ZATCA might change requirements. For instance, new phase might mandate additional fields (like including Buyer ID even for B2C above a threshold, or new cryptographic algorithms). The module developers likely update as needed.

Using the ZATCA Compliance module ensures every invoice you issue in KSA is properly formatted, digitally signed, and (if required) reported/cleared through ZATCAs platform. This protects your business from penalties and gives confidence to your customers that your invoices are authentic and claimable. It does add steps to your invoicing workflow, but those steps are largely automated with this module making compliance as seamless as possible in the background of your accounting process.

Screens & fields reference

Use these screens and fields to complete tasks inside ZATCA Compliance in XFatora.

Automations & notifications

Review automation rules and notifications available in ZATCA Compliance in XFatora.

Reports & dashboards

Track KPIs and dashboards powered by ZATCA Compliance in XFatora.

Common mistakes

• Skipping required configuration before the first workflow.
• Not assigning the correct permissions for team roles.
• Forgetting to review automation or notification settings.

FAQs

Troubleshooting

Related modules