IntegrationsZATCA (KSA)

ZATCA Phase 2 (KSA)

ZATCA Phase 2 (“Fatoorah”) requires every KSA invoice to be cryptographically signed and either reported (B2C) or cleared (B2B) before issuance. Novex handles the signing, reporting, QR code, and PDF stamp once you upload your CSID certificate and pick the environment.

Prerequisites

  • A registered Saudi taxpayer record at ZATCA.
  • A Fatoorah onboarding session completed — you must have generated your Compliance Certificate (CSID) via the ZATCA portal.
  • Decided whether you’re starting in sandbox or going straight to production.

One-time setup

  1. In Novex, go to Settings → Compliance → ZATCA.
  2. Pick the environment: sandbox (for testing) or production (live).
  3. Upload your CSID certificate (.crt or .p12 — both accepted).
  4. Upload (or enter) your private key — encrypted at rest with the tenant secret-vault key.
  5. Set your registered taxpayer info: VAT number, CR number, registered name (Arabic + English), branch ID, national address.
  6. Save. Novex performs a synthetic ping to ZATCA to validate the cert is accepted before persisting.

Sandbox vs production

SandboxProduction
ZATCA endpointgw-fatoora-sb.zatca.gov.sagw-fatoora.zatca.gov.sa
Invoices issuedTest only — never real tax liabilityReal invoices; final
Cert validityIssued by ZATCA sandbox UIIssued via Fatoorah onboarding
QR codesStamped, valid sandbox-sideStamped, full TLV-encoded

Start in sandbox. Send 3-5 test invoices end-to-end. Once you’ve verified the stamped PDFs and the ZATCA portal shows them under your sandbox account, swap the environment to production.

How signing works (under the hood)

When you click Issue on a KSA invoice:

  1. Novex builds the UBL 2.1 XML payload per the ZATCA spec.
  2. Computes the invoice hash (SHA-256) and the previous-invoice hash (chain).
  3. Signs the canonicalised XML with your private key (ECDSA over the cert’s SECP256R1 curve).
  4. POSTs to the ZATCA endpoint with mTLS + Basic auth (the CSID-derived credentials).
  5. Receives a cleared XML + QR string back.
  6. Embeds the QR as a 2D barcode + the cleared-stamp metadata into the PDF.

Troubleshooting

  • 403 from ZATCA — Most often a cert mismatch (sandbox cert hitting prod, or vice versa). Check Settings → Compliance → ZATCA → environment matches the cert you uploaded.
  • 400 with VR-01 / VR-02 — Validation rule failure. The error detail lists which field. Common cause: missing nationalAddress on the buyer (for B2G invoices it’s required).
  • Cert about to expire — ZATCA emails 30 days in advance. Re-onboard via the ZATCA portal, re-upload to Novex. The chain breaks if the cert lapses mid-month.
  • “Previous-invoice hash mismatch” — The chain depends on the previous cleared invoice’s hash. If you ever manually restored from a backup you may need to re-anchor; email support@nov3x.com.

What Novex does NOT do

  • Help you onboard with ZATCA. That’s a one-time interaction with ZATCA’s own portal — we can’t automate it.
  • Store your CSID private key in plaintext. It’s encrypted at rest via the tenant secret-vault.
  • Cross the prod/sandbox boundary. Each tenant picks one environment; switching rotates the credential set.

Next

InvoicesWhatsApp Business