ZATCA Phase 2 E-Invoicing API: Connecting a Desktop POS to Fatoora
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
| Item | Detail |
|---|---|
| Client | Not disclosed |
| Client’s system | Own desktop billing/POS software (kept as is) |
| Our service | Hosted ZATCA Phase 2 API + CSID onboarding + integration guide |
| Documents covered | Simplified and standard tax invoices, credit notes, debit notes, prepayment invoices |
| Result | All 6 document types passed ZATCA validation with zero errors and zero warnings before go-live |
| Price | Setup 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
- The POS sends the sale as JSON to
POST /api/pos/invoices(items, quantities, VAT-inclusive prices, payment method). - 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.
- It signs the XML with the taxpayer’s cryptographic stamp and creates the Phase 2 QR code.
- 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.
- Standard (B2B) invoice: the API sends it to Fatoora for clearance in real time and returns ZATCA’s cleared XML and QR.
- 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.
| Requirement | Phase 1 – Generation | Phase 2 – Integration |
|---|---|---|
| Start | 4 December 2021, all VAT-registered taxpayers | 1 January 2023, in waves by revenue |
| Invoice format | Electronic, structured; no handwritten invoices | UBL 2.1 XML (standard and simplified) |
| Connection to ZATCA | None | API link to the Fatoora platform |
| Device registration | None | Each invoicing unit onboarded with a CSID (cryptographic stamp identifier) |
| Digital signature | Not required | Every invoice signed (cryptographic stamp) |
| QR code | Basic QR on simplified invoices (seller, VAT no., time, totals) | Extended QR with invoice hash, signature and public key |
| Tamper protection | Basic | Invoice hash chain (PIH), counter (ICV) and UUID on every invoice |
| B2B (standard) invoices | Issued locally | Cleared by ZATCA in real time before sharing with the buyer |
| B2C (simplified) invoices | Issued locally | Reported 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:
| Wave | Revenue subject to VAT above | Integrate by |
|---|---|---|
| Wave 25 | SAR 187,500 in 2022, 2023, 2024 or 2025 | 1 February 2027 |
| Wave 24 | SAR 375,000 in 2022, 2023 or 2024 | 30 June 2026 |
| Wave 23 | SAR 750,000 in 2022, 2023 or 2024 | 31 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:
| Requirement | What it means | How our API handles it |
|---|---|---|
| CSR | Certificate request holding your VAT no., CR, branch and address | Generated from the company data you enter in the onboarding screen |
| Compliance CSID (CCSID) | Temporary certificate issued with an OTP from your Fatoora account | Requested by the API when you submit the OTP |
| Compliance checks | Sample invoices, credit and debit notes that ZATCA must accept | Run automatically for B2B and B2C types |
| Production CSID (PCSID) | The live certificate used to sign real invoices | Requested after the checks pass; stored encrypted |
| UBL 2.1 XML | ZATCA’s invoice data format | Built from your JSON; you never write XML |
| Cryptographic stamp | ECDSA (secp256k1) signature on every invoice | Applied with your private key, kept encrypted on our server |
| Invoice hash, ICV, PIH, UUID | Each invoice carries its own hash, a running counter and the previous invoice’s hash | Assigned in strict order, safe under many parallel sales |
| Phase 2 QR code | Base64 TLV holding seller, VAT no., time, totals, hash, signature, public key | Returned in every response, ready to print |
| Clearance (B2B) | Standard invoices approved by ZATCA before the buyer receives them | Real-time call; ZATCA’s cleared XML returned |
| Reporting (B2C) | Simplified invoices reported within 24 hours | Background reporting with automatic retries |
| Credit / debit notes | Must reference the original invoice and give a reason | originalInvoiceNumber + reason fields |
| Prepayments | Advance-payment invoice (type 386), then a final invoice that deducts it | Supported, including the prepayment reference lines ZATCA checks |
| Archive copy | Signed XML; PDF/A-3 with embedded XML is the usual readable copy | XML 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.
- Send your company data: Arabic legal name, VAT number, CR number, branch name and national address (building no., street, district, city, postal code).
- Receive your keys: a POS key for your software and an onboarding key for setup.
- Sandbox: generate the CSR, request the compliance CSID (OTP
123456), run the compliance checks, then send test invoices from your own system. - Simulation: repeat with an OTP from the Fatoora simulation portal and test real reporting and clearance.
- Production: repeat with an OTP from the live Fatoora portal and switch your POS to live.
- 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 month | Setup and first year | Annual renewal (from year 2) |
|---|---|---|
| Up to 5,000 | SAR 5,000 | SAR 1,500 |
| Up to 10,000 | SAR 6,500 | SAR 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.
- 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
Frequently asked questions
Can I keep my current POS and still comply with ZATCA Phase 2?
How much does ZATCA Phase 2 integration cost with Alwajeez Tech?
What happens if I send more documents than my monthly limit?
How long does the integration take?
What is a CSID and how do I get one?
What is the difference between clearance and reporting?
Will ZATCA reject my invoice over a 1-halala rounding difference?
Can I issue credit notes and prepayment invoices through the API?
Do I get the XML and QR for my own PDF invoice?
Which ZATCA wave am I in?
What happens if my business misses its integration deadline?
Is Alwajeez Tech ZATCA certified?
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