Gulf E-Invoice Pro – ZATCA & UAE e-Invoicing for WooCommerce

WordPress / WooCommerce plugin by Zaki International (engzaki.pro). Slug zi-gulf-einvoice · class prefix ZIGE_ · text domain zi-gulf-einvoice · PHP 7.4–8.3 · WordPress 6.0+ (tested 6.8) · WooCommerce 7.0+ (HPOS and Cart/Checkout blocks compatible). Product page: https://engzaki.pro/en/products/uae-zatca-e-invoicing-woocommerce

It issues legally structured tax invoices and credit notes for WooCommerce orders in Saudi Arabia (ZATCA / FATOORA) and the United Arab Emirates (FTA / MoF eInvoicing): bilingual Arabic/English printable invoices, TLV QR codes, UBL 2.1 XML for ZATCA with invoice counter + hash chain, the full ZATCA Phase 2 onboarding / signing / clearance / reporting flow, PINT AE XML for the UAE and a configurable connector to your UAE Accredited Service Provider (ASP).

---

Contents

1. Regulatory notes, sources and dates
2. What the plugin does – and what it does not
3. Verified vs. needs testing
4. Requirements
5. Installation
6. Configuration, screen by screen
7. How it works
8. Developer hooks
9. Troubleshooting
10. FAQ
11. Licensing, updates, uninstall

---

Regulatory notes, sources and dates

Researched on 9 October 2026. Regulations change – confirm against the official sources before relying on a date.

Saudi Arabia – ZATCA e-invoicing (FATOORA)

Topic	Summary	Source
Phase 1 (Generation)	In force since 4 December 2021: invoices must be generated by a compliant electronic solution; simplified invoices carry a QR code (TLV, base64) with seller name, VAT number, timestamp, total with VAT and VAT total.	zatca.gov.sa – What is e-invoicing
Phase 2 (Integration)	From 1 January 2023, in waves: UBL 2.1 XML, UUID, invoice counter (ICV), previous-invoice hash (PIH), XAdES cryptographic stamp with a ZATCA-issued CSID, QR with 8–9 fields; standard (B2B) invoices are cleared before sharing, simplified (B2C) invoices are reported within 24 hours.	same; ZATCA XML implementation standard and security features specification
Onboarding	Generate key + CSR (secp256k1, ZATCA certificate-template OID 1.3.6.1.4.1.311.20.2, SAN with EGS serial, VAT number, invoice type, address, industry) → OTP from the FATOORA portal → compliance CSID → compliance invoice checks → production CSID.	ZATCA FATOORA portal user guide / developer portal
Waves	ZATCA notifies taxpayers of their wave in advance. Wave 25 (announced 24 July 2026): VAT-taxable turnover above SAR 187,500 in any of 2022–2025, comply by 1 February 2027.	EY Global Tax News, 10 Aug 2026
API endpoints	https://gw-fatoora.zatca.gov.sa/e-invoicing/{developer-portal | simulation | core} – /compliance, /compliance/invoices, /production/csids, /invoices/reporting/single, /invoices/clearance/single (Accept-Version V2).	ZATCA developer portal

United Arab Emirates – eInvoicing programme (MoF / FTA)

Topic	Summary	Source
Model	Decentralised Continuous Transaction Control and Exchange (Peppol 5-corner): C1 supplier → C2 supplier's ASP → C3 buyer's ASP → C4 buyer, with tax data reported to C5 (FTA). Invoice data format PINT AE. PDFs, Word files, images and e-mails are not e-invoices.	mof.gov.ae – eInvoicing
Legal basis	Ministerial Decisions 64/2025 (ASP accreditation), 243/2025 (system), 244/2025 (implementation), Cabinet Decision 106/2025 (penalties), MR 56/2026 and MR 66/2026 (amendments), MD 168/2026.	same
Timeline (after the May 2026 amendment)	Pilot / voluntary from 1 July 2026. Revenue ≥ AED 50 m: appoint an ASP by 30 October 2026, go live 1 January 2027. Other businesses: ASP by 31 March 2027, go live 1 July 2027. Government entities: ASP by 31 March 2027, go live 1 October 2027.	MR 66/2026 (PDF), WAM, MoF programme deck 30 Jun 2026
Scope	B2B, B2G (and G2B/G2G). B2C is outside the system for now (until a later ministerial decision).	Ministerial Decision 244/2025 as summarised by MoF and advisers
ASPs	Only Accredited Service Providers exchange invoices on Peppol and report to the FTA (32 approved in May 2026, 41 pre-approved by 30 June 2026).	MoF announcements
PINT AE	CustomizationID urn:peppol:pint:billing-1@ae-1, ProfileID urn:peppol:bis:billing, transaction-type flags in ProfileExecutionID (8 positions), endpoint scheme 0235 (TIN), emirate codes AUH/DXB/SHJ/AJM/UAQ/RAK/FUJ, line amounts in AED (ItemPriceExtension), HS / service accounting codes.	docs.peppol.eu – PINT AE (v1.0.4 rules and examples)
VAT invoice content	Independently of e-invoicing, a UAE tax invoice must show "Tax Invoice", supplier and (for registered recipients) recipient TRN, sequential number, dates, description, quantity, unit price, VAT rate and amount in AED, discounts and totals.	Federal Decree-Law on VAT, Executive Regulation (Art. 59)

Honest scope statement

• Saudi Arabia: the plugin is an e-invoice generation solution (EGS) for WooCommerce. ZATCA does not certify plugins; you onboard your own EGS unit with your own OTP, run the compliance checks, and remain responsible for your invoices.
• UAE: a WordPress plugin cannot transmit e-invoices to the FTA itself – only an ASP can. The plugin produces compliant tax invoices (PDF/HTML for the customer), PINT AE XML for each document, and hands it to your ASP through a configurable REST connector. Exact field mapping, Peppol registration and final validation happen at your ASP.
• Nothing in this plugin is legal or tax advice.

---

What the plugin does – and what it does not

Does

• Creates the invoice automatically when an order reaches the statuses you choose (default Processing / Completed), once per order; manual "Create tax invoice now" on the order screen.
• Credit notes automatically for refunds (line refunds and amount-only refunds, split over the original VAT categories).
• Gap-free sequential numbering per country and document type (database lock), UUID v4, per-EGS invoice counter and previous-invoice-hash chain (ZATCA).
• Saudi simplified (B2C) and standard (B2B, when the buyer gives a valid VAT number) tax invoices, credit notes (381) – debit notes (383) are supported by the XML builder (used by the compliance checks).
• ZATCA Phase 1: TLV QR (5 tags), UBL 2.1 XML archive with ICV/PIH/UUID.
• ZATCA Phase 2: key + CSR, compliance CSID, compliance checks, production CSID, renewal; XAdES-signed XML with QR (8/9 tags); reporting (B2C) and clearance (B2B) with automatic retries; stores ZATCA's cleared XML and uses its QR.
• UAE tax invoices (Arabic/English, TRN, VAT breakdown, AED equivalents + exchange rate for other currencies), PINT AE invoice / credit note XML, ASP connector (JSON template or raw XML; Bearer / Basic / API-key header / HMAC auth; status + reference mapping; signed status webhook).
• Archive with filters, XML / HTML (and PDF when mPDF is installed) downloads, details page with the full ZATCA / ASP response, resend by e-mail, retry, bulk ZIP (XML + HTML + CSV) and CSV export.
• Customer side: links in WooCommerce e-mails, optional XML/PDF attachments, downloads in My Account (signed, unguessable links).
• Business checkout fields (classic + block checkout): VAT number / TRN, building number, district; editable on the order.
• Product fields for UAE classification (item type, HS code, service accounting code).
• Logs (no secrets), readiness checklists for both countries, admin column in the orders list (HPOS and legacy).

Does not

• It is not a UAE ASP and does not connect to Peppol directly.
• It does not produce a PDF by itself (no bundled PDF library): customers get a print-ready bilingual HTML invoice ("Save as PDF"); if mPDF is available (class \Mpdf\Mpdf, e.g. via another plugin or Composer) real PDFs are generated and attached. Any engine can be plugged in via the zige_pdf_bytes filter.
• No ZATCA "Phase 1 only" invoices for non-SAR currencies without an exchange rate (the VAT total in SAR is mandatory) – set the rates in Settings.
• No automatic correction of rejected documents (they stay in the archive and chain; fix the data, issue a credit note and a new invoice).

---

Verified vs. needs testing

Area	Status
ZATCA UBL XML (simplified + standard invoice, credit note, debit note), invoice hash, ECDSA signature, XAdES block, QR (Phase 2)	Verified – plugin code submitted to the ZATCA developer-portal sandbox /compliance/invoices: all six document types returned PASS with no warnings.
ZATCA onboarding flow (CSR → compliance CSID with OTP 123345 → compliance checks → production CSID)	Verified in the sandbox with the plugin's own classes (PHP 8.3 and 7.4).
ZATCA reporting (B2C invoice + credit note) and clearance (B2B) incl. storing the cleared XML	Verified in the sandbox (REPORTED / CLEARED, status PASS).
X.509 parsing (issuer, serial, public key, certificate signature, digests)	Verified against a real ZATCA simulation certificate from a published sample (byte-identical digests).
QR encoder (ISO 18004, versions 1–40, all ECC levels, masks)	Verified module-by-module against the qrcode Python library on 49 symbols.
ZATCA simulation and production portals	Needs testing (beta) – need your OTP from FATOORA. The UI says "beta – verify in ZATCA simulation".
Phase 1 QR / XML	Structure verified (same builder as Phase 2, unsigned).
PINT AE XML	Built from the official PINT AE 1.0.4 examples and reviewed against the jurisdiction rules (transaction-type flags, endpoint 0235, emirate codes, AED line amounts, exchange rate, aedtotal-incl-vat, HS / SAC placement, credit-note reason). Not machine-validated against the official schematron (needs an XSLT 2.0 engine) – validate with your ASP's sandbox.
ASP connector	Verified against a mocked API (request body, auth header, status/reference mapping, HMAC webhook). Needs testing with your real ASP.
WooCommerce UI (order screen, checkout fields, My Account, e-mails)	Code reviewed + lint clean on PHP 8.3 / 7.4; run your own end-to-end test on a staging store (classic and block checkout).
mPDF output	Not tested (mPDF not bundled).

---

Requirements

• WordPress 6.0+, WooCommerce 7.0+, PHP 7.4–8.3.
• PHP extensions: openssl (with the secp256k1 curve – standard OpenSSL builds have it; some FIPS builds do not), dom, json, mbstring (recommended), zip (optional, for ZIP export).
• Outbound HTTPS to gw-fatoora.zatca.gov.sa (Phase 2) and to your ASP (UAE).
• Site timezone set correctly (Asia/Riyadh or Asia/Dubai) – invoice dates and times use it.

Installation

1. Plugins → Add New → Upload Plugin → zi-gulf-einvoice-1.0.0.zip → Install → Activate (WooCommerce must be active).
2. E-Invoicing → License: paste your EZ-… key → Activate.
3. E-Invoicing → Settings → General: choose which seller issues invoices, the automatic statuses, logo and notes.
4. Settings → Saudi Arabia and/or Settings → UAE: seller details exactly as on your VAT certificate / trade license.
5. Saudi Phase 2: E-Invoicing → ZATCA onboarding (sandbox → simulation → production), then set ZATCA phase to Phase 2.
6. UAE: Settings → UAE ASP connector with the details from your ASP; E-Invoicing → UAE readiness.
7. Place a test order on a staging site and check E-Invoicing → Documents.

Configuration, screen by screen

Dashboard

Counters per country, documents that need attention (pending / error / rejected), Saudi checks (seller data, phase, onboarding step, wave note), UAE checks (seller data, ASP) with the timeline for your business size, and environment checks (license, OpenSSL + secp256k1, DOM, ZipArchive, PDF engine, timezone).

Documents

Filter by country, type, transmission status, dates and search (number, buyer, VAT, order ID). Export the current filter as ZIP (XML + printable HTML + summary.csv) or CSV (UTF-8 BOM, formula-injection safe). Bulk: download selected, send / retry to ZATCA or ASP, e-mail to customers. Details shows hashes, ICV, environment, the full ZATCA / ASP response, the XML and the document's log.

Settings → General

• Which seller issues the invoice – store base country, always SA, always AE, or by billing country.
• Enable Saudi / UAE profiles, automatic statuses, credit notes for refunds, skip free orders, number padding.
• Business customers – adds VAT number / TRN, building number and district to classic and block checkout (validated: Saudi 3XXXXXXXXXXXXX3, UAE 1XXXXXXXXXXXXXX).
• Logo, note, footer; e-mail link; attach XML / PDF; My Account downloads; log retention; delete data on uninstall.

Settings → Saudi Arabia

Seller names (English + Arabic – the Arabic name is used as the legal name in the XML and QR when filled), VAT number, seller ID type + number (CRN, MOM, MLS, 700, SAG, OTH), national address (street, 4-digit building number, additional number, district, city, 5-digit postal code), number prefixes ({Y} = year; running number never resets), ZATCA phase, category and VATEX reason for 0 % lines (Z / E / O), SAR exchange rates for foreign-currency orders.

Settings → UAE

Legal and Arabic names, trade name, TRN, TIN / Peppol endpoint (defaults to the first 10 digits of the TRN), legal registration type + number + issuing authority, address with emirate, prefixes, 0 % category / exemption code, default item type, HS code and service accounting code, e-commerce transaction flag, endpoint for unregistered buyers (from your ASP), payment due days, AED exchange rates, business size (timeline).

Settings → UAE ASP connector

URL, method, body format (JSON template with placeholders or raw XML), authentication (none, Bearer, Basic, API-key header, HMAC-SHA256 of timestamp.body with X-Timestamp), extra headers, response status path + success values, reference path, auto-send, include B2C, callback secret, timeout. A request preview (secrets masked) is built from your latest UAE document. Status webhook: POST /wp-json/zi-gulf-einvoice/v1/asp-callback with JSON { "uuid" | "number" | "reference", "status", "message" } and header X-Signature: hex(HMAC-SHA256(raw body, callback secret)).

ZATCA onboarding

1. Environment (sandbox / simulation / production) + EGS details → Generate key and CSR (key encrypted at rest).
2. OTP → compliance CSID.
3. Run compliance checks – signs and submits sample standard/simplified invoices, credit and debit notes (according to the invoice types of the EGS).
4. Request production CSID; later Renew with a new OTP. Reset wipes keys and CSIDs. The page is labelled beta – verify in ZATCA simulation.

UAE readiness

Timeline for your size, the 5-corner model explained, automatic checks and a manual checklist (ASP appointed, Peppol ID, API access, product codes, TRN collection, sandbox test, rejection handling, archiving).

Logs

Every issue / send / onboarding step with level and message (secrets are never logged); filter by level; clear.

License

Activate / check / deactivate (frees the activation on engzaki.pro).

Order screen

Meta box: documents with View / PDF / XML / E-mail / Send / Details, data warnings before issuing (e.g. incomplete buyer national address for B2B), "Create tax invoice now", and buyer VAT / building number / district fields. Orders list: "Tax invoice" column.

Products

Inventory tab: e-invoicing item type, HS code, service accounting code (UAE).

How it works

1. Trigger – woocommerce_order_status_{status} (priority 5, before WooCommerce sends its e-mails) or the manual button; refunds via woocommerce_refund_created.
2. Document – lines from order items, shipping and fees (negative fees become document-level allowances). Line net = WooCommerce line total excl. VAT; VAT rate from the order's own tax lines; VAT per category = taxable × rate (2 dp); totals derived from those. Foreign currency → local-currency VAT using your rate table.
3. Issue (inside a MySQL GET_LOCK) – next number, UUID, issue date/time (site timezone); for Saudi documents ICV = previous + 1 and PIH = previous hash (first PIH = base64(hex(SHA-256("0")))). The chain restarts when the EGS changes (Phase 1 → Phase 2, new environment).
4. XML – ZATCA UBL 2.1 (reporting:1.0, InvoiceTypeCode 388/381/383 with name 0100000/0200000) or PINT AE. XML is written without insignificant whitespace, so the invoice hash (C14N of the invoice without UBLExtensions, cac:Signature and the QR reference, SHA-256) is stable.
5. Phase 2 signing – ECDSA-SHA256 over the hash with the EGS key, XAdES SignedProperties (signing time, certificate digest, issuer, serial), QR tags 1–8 (+9 certificate signature for simplified). A self-check recomputes the hash of the signed XML.
6. Transmission – queued with Action Scheduler (or WP-Cron); clearance for standard, reporting for simplified (303 → falls back to reporting); retried every 15 minutes for 7 days (max 8 attempts). UAE documents go to the ASP when B2B (or B2C if enabled).
7. Delivery – the customer link ?zige_doc={id}&f=html|pdf|xml&t={HMAC} works without login and cannot be guessed.

Database tables: {prefix}zige_invoices (archive: data snapshot JSON, XML, cleared XML, hashes, QR, transmission status/response), {prefix}zige_logs. Options: zige_settings, zige_zatca (onboarding state, encrypted secrets), zige_counters, zige_chain_sa, zige_license_state.

Developer hooks

Hook	Type	Purpose
zige_is_licensed	filter (bool)	Force invoicing on (your own sites).
zige_capability	filter	Capability for the admin screens (default manage_woocommerce).
zige_order_country	filter	Override which seller (SA / AE) invoices an order.
zige_should_invoice_order	filter	Skip specific orders.
zige_buyer, zige_document	filter	Adjust the buyer / the whole document before issuing.
zige_fx_rate	filter	Supply live exchange rates.
zige_payment_means_code	filter	Map gateways to UN/ECE 4461 codes.
zige_ae_transaction_flags	filter	PINT AE transaction-type flags.
zige_asp_should_send, zige_asp_placeholders, zige_asp_request	filter	Customise ASP delivery.
zige_pdf_bytes	filter	Return PDF bytes from your own engine.
zige_invoice_html	filter	Change the printable invoice.
zige_zatca_base_url	filter	Point the ZATCA client elsewhere (proxies).
zige_document_issued, zige_zatca_submitted, zige_asp_sent	action	React to events.

Troubleshooting

Symptom	Fix
"Invoice generation is disabled until the plugin license is activated"	Activate the key under License (or the 7-day grace period expired while engzaki.pro was unreachable).
"OpenSSL does not support secp256k1"	Ask your host for a standard OpenSSL build (FIPS mode disables secp256k1).
ZATCA invalid-request / 400 on the compliance CSID	OTP expired or already used, or EGS fields contain forbidden characters (! @ # $ % & * _ < =). Generate a new OTP.
BR-KSA-… errors on standard invoices	Buyer national address incomplete – add building number (4 digits), district and 5-digit postal code on the order.
Document stays Pending	WP-Cron / Action Scheduler is not running – check WooCommerce → Status → Scheduled Actions, or use "Send to ZATCA / ASP".
ZATCA 401	CSID expired or revoked – renew in ZATCA onboarding.
"No USD → SAR exchange rate is set"	Add the currency to the rate table in Settings.
ASP rejects the XML	Open Documents → Details for the ASP's response; adjust HS / SAC codes, endpoint for unregistered buyers or the JSON template as your ASP requires.
Secrets lost after migrating the site	Secrets are encrypted with the WordPress salts; if the salts changed, re-enter the ASP token and redo ZATCA onboarding.
Invoice total differs by 0.01 from the WooCommerce total	The invoice recalculates VAT per category (as ZATCA / PINT rules require) while WooCommerce may round per line. Use "Round tax at subtotal level" in WooCommerce → Settings → Tax to align.

FAQ

Is the plugin ZATCA-certified? – ZATCA does not certify WordPress plugins. Each taxpayer onboards its own EGS unit; the compliance checks in the onboarding screen are ZATCA's own validation.

Can it send invoices to the UAE FTA? – No plugin can. It sends PINT AE XML to your Accredited Service Provider, who exchanges it on Peppol and reports to the FTA.

Do I need Phase 2 now? – Only when ZATCA has notified your wave. Until then Phase 1 mode issues compliant invoices with the 5-field QR.

What about B2C in the UAE? – B2C is currently outside the UAE e-invoicing system; you still issue tax invoices (this plugin does), but they are not sent to the ASP unless you enable "Include B2C".

Can I change an issued invoice? – No. Issued documents are immutable; issue a credit note (refund in WooCommerce) and a new invoice.

Are my keys safe? – The ZATCA private key and all secrets are encrypted (AES-256-GCM, key derived from the WordPress salts), never printed and never logged.

Multi-currency? – Yes, with exchange rates in Settings (or the zige_fx_rate filter). ZATCA requires the VAT total in SAR; UAE law requires the VAT amount in AED.

Does it work with HPOS and the block checkout? – Yes, both are declared compatible.

Licensing, updates, uninstall

• License check POST https://engzaki.pro/api/license/validate { key, domain, product: "zi-gulf-einvoice" }, cached 12 h, 7-day grace period offline.
• Updates POST https://engzaki.pro/api/plugins/zi-gulf-einvoice/update – shown in Dashboard → Updates.
• Without a valid license: settings, onboarding screens, archive and downloads keep working; creating documents, onboarding actions and transmissions are disabled with a notice and a link to buy.
• Uninstall keeps all data unless Delete data on uninstall is ticked (then tables, options, keys and transients are removed). Keep the legally required archive (KSA 6 years, UAE 5 years) – export first.

Credits

QR encoder structure follows Project Nayuki's QR Code generator (MIT). ZATCA signing layout cross-checked with the open-source php-zatca-xml project (MIT) and ZATCA's published samples. PINT AE structure follows the OpenPeppol PINT AE examples.

© Zaki International – GPL-2.0-or-later.