Retail & POS ZATCA & Financial Compliance Saudi Arabia · Vision 2030

ZATCA Phase 2 E-Invoicing API: Connecting a Desktop POS to Fatoora

Alwajeez Tech engineering team • Published 18 Nov 2026 • Last checked 18 Nov 2026
Share:
⚡

Quick Answer

Alwajeez Tech, a Jeddah software company, runs a hosted ZATCA Phase 2 e-invoicing API. Your existing POS or ERP sends each sale as JSON. The API builds the UBL 2.1 XML, signs it, adds the Phase 2 QR code, and clears or reports it to ZATCA's Fatoora platform. Setup and the first year are SAR 5,000 one time, then SAR 1,500 a year renewal from year 2, covering up to 5,000 documents a month.

This project shows how we connected a client’s own desktop POS to ZATCA Phase 2 without changing its billing system. The same API works for any POS, ERP or custom software that can send an HTTPS request.

At a glance

ItemDetail
ClientNot disclosed
Client’s systemOwn desktop billing/POS software (kept as is)
Our serviceHosted ZATCA Phase 2 API + CSID onboarding + integration guide
Documents coveredSimplified and standard tax invoices, credit notes, debit notes, prepayment invoices
ResultAll 6 document types passed ZATCA validation with zero errors and zero warnings before go-live
PriceSetup and first year SAR 5,000, then SAR 1,500/year renewal, VAT included, up to 5,000 documents/month

The project: Phase 2 without replacing the POS

The challenge. The client already had its own desktop billing software and did not want to replace it. It needed four things from a provider:

  • Send every sale to ZATCA through an API, with no change to how cashiers work.
  • Get the Phase 2 QR code back at the moment of sale, to print on the receipt.
  • Get the signed XML back, so its own software can build a PDF/A-3 invoice.
  • Support prepaid service packages (advance payments) and credit notes.

Its prices already include VAT, so it also asked whether a 1-halala rounding difference would get an invoice rejected.

The solution. We gave the client a dedicated, hosted instance of our ZATCA Phase 2 API with its own database, its own cryptographic keys and two API keys: one for the POS, one for onboarding. The client moves itself through ZATCA’s three environments — developer sandbox, simulation, production — from a Swagger screen, using OTP codes from its own Fatoora account.

How a sale flows

  1. The POS sends the sale as JSON to POST /api/pos/invoices (items, quantities, VAT-inclusive prices, payment method).
  2. The API calculates net, VAT and totals, builds the UBL 2.1 XML, and assigns the invoice counter (ICV), previous-invoice hash (PIH) and UUID.
  3. It signs the XML with the taxpayer’s cryptographic stamp and creates the Phase 2 QR code.
  4. Simplified (B2C) invoice: the QR and signed XML return to the POS within seconds; the API reports the invoice to Fatoora in the background and retries automatically if the connection drops.
  5. Standard (B2B) invoice: the API sends it to Fatoora for clearance in real time and returns ZATCA’s cleared XML and QR.
  6. The POS prints the QR and stores the XML for the PDF/A-3 copy; the API keeps the full submission history.

Rounding answered. When prices include VAT, a total can differ by a halala. The API records that difference in the invoice’s official rounding field (PayableRoundingAmount), so the payable amount matches the POS total. ZATCA’s validation accepted this with no warnings in testing.

Phase 1 vs Phase 2: what ZATCA requires

Phase 1 (Generation) made electronic invoices mandatory from 4 December 2021; Phase 2 (Integration), in force since 1 January 2023, connects your system to ZATCA and is rolled out in waves.

RequirementPhase 1 – GenerationPhase 2 – Integration
Start4 December 2021, all VAT-registered taxpayers1 January 2023, in waves by revenue
Invoice formatElectronic, structured; no handwritten invoicesUBL 2.1 XML (standard and simplified)
Connection to ZATCANoneAPI link to the Fatoora platform
Device registrationNoneEach invoicing unit onboarded with a CSID (cryptographic stamp identifier)
Digital signatureNot requiredEvery invoice signed (cryptographic stamp)
QR codeBasic QR on simplified invoices (seller, VAT no., time, totals)Extended QR with invoice hash, signature and public key
Tamper protectionBasicInvoice hash chain (PIH), counter (ICV) and UUID on every invoice
B2B (standard) invoicesIssued locallyCleared by ZATCA in real time before sharing with the buyer
B2C (simplified) invoicesIssued locallyReported to ZATCA within 24 hours

Who must comply now (waves)

ZATCA tells each taxpayer directly at least six months before its integration date. The latest waves:

WaveRevenue subject to VAT aboveIntegrate by
Wave 25SAR 187,500 in 2022, 2023, 2024 or 20251 February 2027
Wave 24SAR 375,000 in 2022, 2023 or 202430 June 2026
Wave 23SAR 750,000 in 2022, 2023 or 202431 March 2026

As of 18 Nov 2026

Wave 25 halved the threshold, so many small shops, salons, laundries and restaurants now fall inside Phase 2. Sources: Grant Thornton KSA – Wave 25, KPMG – Wave 25, EY – Phase 2 waves, LookupTax – Wave 23, Alvarez & Marsal – Wave 24.

Phase 2 technical requirements (CSID, UBL, signing)

Every Phase 2 invoice must be a signed UBL 2.1 XML file, chained to the one before it, from a unit registered with ZATCA. Our API handles each piece:

RequirementWhat it meansHow our API handles it
CSRCertificate request holding your VAT no., CR, branch and addressGenerated from the company data you enter in the onboarding screen
Compliance CSID (CCSID)Temporary certificate issued with an OTP from your Fatoora accountRequested by the API when you submit the OTP
Compliance checksSample invoices, credit and debit notes that ZATCA must acceptRun automatically for B2B and B2C types
Production CSID (PCSID)The live certificate used to sign real invoicesRequested after the checks pass; stored encrypted
UBL 2.1 XMLZATCA’s invoice data formatBuilt from your JSON; you never write XML
Cryptographic stampECDSA (secp256k1) signature on every invoiceApplied with your private key, kept encrypted on our server
Invoice hash, ICV, PIH, UUIDEach invoice carries its own hash, a running counter and the previous invoice’s hashAssigned in strict order, safe under many parallel sales
Phase 2 QR codeBase64 TLV holding seller, VAT no., time, totals, hash, signature, public keyReturned in every response, ready to print
Clearance (B2B)Standard invoices approved by ZATCA before the buyer receives themReal-time call; ZATCA’s cleared XML returned
Reporting (B2C)Simplified invoices reported within 24 hoursBackground reporting with automatic retries
Credit / debit notesMust reference the original invoice and give a reasonoriginalInvoiceNumber + reason fields
PrepaymentsAdvance-payment invoice (type 386), then a final invoice that deducts itSupported, including the prepayment reference lines ZATCA checks
Archive copySigned XML; PDF/A-3 with embedded XML is the usual readable copyXML returned as Base64 for your PDF/A-3

How to connect your POS or ERP

Any system that can send an HTTPS request with JSON can connect — desktop POS, cloud POS, ERP, accounting or custom software, in any language.

  1. Send your company data: Arabic legal name, VAT number, CR number, branch name and national address (building no., street, district, city, postal code).
  2. Receive your keys: a POS key for your software and an onboarding key for setup.
  3. Sandbox: generate the CSR, request the compliance CSID (OTP 123456), run the compliance checks, then send test invoices from your own system.
  4. Simulation: repeat with an OTP from the Fatoora simulation portal and test real reporting and clearance.
  5. Production: repeat with an OTP from the live Fatoora portal and switch your POS to live.
  6. Print and store: print the returned QR on each receipt and keep the returned XML (or your PDF/A-3 built from it).

Sample request (simplified invoice, VAT-inclusive prices)

POST /api/pos/invoices
X-Api-Key: <your POS key>

{
  "invoiceNumber": "INV-000123",
  "issueDateTime": "2026-11-18T14:30:00+03:00",
  "documentType": "invoice",
  "invoiceKind": "simplified",
  "pricesIncludeVat": true,
  "expectedTotalIncludingVat": 46.00,
  "paymentMeans": "cash",
  "lines": [
    { "name": "Item A", "quantity": 2, "unitPrice": 15.00, "vatCategory": "S", "vatRate": 15 },
    { "name": "Item B", "quantity": 1, "unitPrice": 16.00, "vatCategory": "S", "vatRate": 15 }
  ]
}

The response returns qrCode, xmlBase64, uuid, icv, invoiceHash, the calculated totals and a status (PENDING_REPORT, REPORTED, CLEARED or FAILED with ZATCA’s messages). Resending the same invoice number returns the stored result, so a dropped connection never creates a duplicate.

Pricing, limits and quota

All plans include hosted API, CSID onboarding in all 3 environments, all 6 document types, integration guide, and WhatsApp support for 1 VAT number and 1 branch.

Documents per monthSetup and first yearAnnual renewal (from year 2)
Up to 5,000SAR 5,000SAR 1,500
Up to 10,000SAR 6,500SAR 3,000

Need more? Each extra 5,000 documents a month adds SAR 1,500 to the first year and SAR 1,500 to the yearly renewal. Contact us. All prices include VAT. Setup and first year are one time.

Already use Alwajeez ERP or POS? ZATCA Phase 2 is a SAR 2,000 one-time add-on there. This plan is for connecting your own POS or ERP.

Limits to know before you sign

  • Your POS needs internet access to reach the API; the QR is created by the API, not offline on the device.
  • Standard (B2B) invoices need ZATCA to be online at the moment of sale, because clearance is real time; if ZATCA is down, the API returns FAILED and you resend.
  • Simplified (B2C) invoices are not blocked by a ZATCA outage: the QR returns at once and reporting is retried in the background within ZATCA’s 24-hour window.
  • Onboarding needs an OTP from your own Fatoora account for simulation and production; we cannot request it for you.
  • Each environment keeps its own invoice counter and hash chain; production always starts from invoice 1.
  • VAT-inclusive totals: rounding differences up to SAR 0.05 are absorbed in the official rounding field; larger gaps are rejected with a clear message.
  • If you leave, we hand over your full submission history (XML files, QR codes, statuses). Private keys are not transferred; your next provider onboards a new unit with a new OTP, and past invoices stay valid.

Connect your POS or ERP to ZATCA

Send us your company name, VAT number and the name of your POS or ERP, and we will set up your sandbox and send you the integration guide.

?

Frequently asked questions

Can I keep my current POS and still comply with ZATCA Phase 2?

Yes. Your POS keeps working as it does; it only adds one API call per sale. The API does the XML, signing, QR and the connection to Fatoora.

How much does ZATCA Phase 2 integration cost with Alwajeez Tech?

Setup and the first year are SAR 5,000 one time, covering up to 5,000 documents a month and all 6 document types. From year 2, annual renewal is SAR 1,500. All prices include VAT.

What happens if I send more documents than my monthly limit?

Nothing stops. The API keeps clearing and reporting your invoices. We send you an automatic email when you pass your monthly limit.

How long does the integration take?

The API side is ready once your company data is in. Most of the time goes into your developer adding the API call to your POS; the sandbox lets them test with real items from day one.

What is a CSID and how do I get one?

A CSID (Cryptographic Stamp Identifier) is the certificate ZATCA issues to each invoicing unit. You get an OTP from your Fatoora portal, enter it in our onboarding screen, and the API requests the CSID for you.

What is the difference between clearance and reporting?

Clearance applies to standard (B2B) invoices: ZATCA approves them in real time before the buyer gets them. Reporting applies to simplified (B2C) invoices: you give the receipt at once and the invoice is reported to ZATCA within 24 hours.

Will ZATCA reject my invoice over a 1-halala rounding difference?

No. When your prices include VAT, the API puts small differences (up to SAR 0.05) in the official rounding field, so the payable amount matches your POS total.

Can I issue credit notes and prepayment invoices through the API?

Yes. Credit and debit notes reference the original invoice and a reason. Prepayment invoices and the final invoices that deduct them are both supported.

Do I get the XML and QR for my own PDF invoice?

Yes. Every response includes the QR code text and the signed XML (Base64), so your software can print the QR and build a PDF/A-3 with the XML embedded.

Which ZATCA wave am I in?

Wave 25 covers businesses whose revenue subject to VAT exceeded SAR 187,500 in any year from 2022 to 2025, with integration due by 1 February 2027. ZATCA notifies each business directly at least six months ahead.

What happens if my business misses its integration deadline?

ZATCA can apply penalties for non-compliance with e-invoicing rules. Start onboarding early: the sandbox and simulation steps take time to complete properly.

Is Alwajeez Tech ZATCA certified?

ZATCA does not issue a certificate for software. It approves software providers for e-invoicing. Alwajeez Tech is a ZATCA-qualified e-invoicing provider.

Connect your POS or ERP to ZATCA

Send us your company name, VAT number and the name of your POS or ERP, and we will set up your sandbox and send you the integration guide.

Request ZATCA Phase 2 Sandbox Onboarding

WhatsApp / phone: +966 55 158 9625

Email: info@alwajeeztech.com

Office: Al Hayat Commercial Center (Level-2, Suite A216), Building 6945, 2344 Abu Bakr Al Siddiq Street, Ash Sharafiyah Dist., Jeddah 23216, Saudi Arabia

Related: Alwajeez Tech: a ZATCA-qualified e-invoicing provider · ALZERP Cloud ERP

Alwajeez Tech is the commercial marketing brand of شركة الأفق الواعدة, delivering Saudi Arabia–focused AI and enterprise software solutions aligned with the strategic objectives of Saudi Vision 2030. We drive the Kingdom's tech sector in accordance with the guidelines of the MCIT, ensuring our AI-driven platforms align with SDAIA standards for data privacy and AI ethics. Our solutions maintain full compliance with ZATCA E-Invoicing (Fatoora) regulations and Saudi tax standards. We adhere to CST cloud service provider registrations and telecom standards, while supporting DGA B2G digital transformation and the 'Government-as-a-Platform' initiative. Our high-performance architectures enable government and private entities to modernize operations, optimize services, and drive sustainable growth. This description is for informational purposes only.

Powering Saudi Arabia with local, trustworthy AI & Software solutions