Download the PHP package khaledhajsalem/zatca-php without Composer

ZATCA PHP Package

A PHP package for ZATCA (Saudi Arabia) Phase 2 e-invoicing. Handles XML generation (UBL 2.1), digital signing, QR codes, and API submission — all without database dependencies.

Table of Contents

• Requirements
• Installation
• Key Concepts
• How It Works (Lifecycle)
• Step 1: Generate CSR & Private Key
• Step 2: Get Your Certificate from ZATCA
• Step 3: Create & Submit an Invoice
• Invoice Types
• Credit & Debit Notes
• Data Reference
• Validation
• Error Handling
• Package Structure
• Testing
• Contributing
• License

Requirements

• PHP 8.0+
• OpenSSL extension
• Composer

Installation

Key Concepts

Before using this package, understand these ZATCA-specific terms:

Invoice Type Codes

Party Identification Schemes

Both seller and buyer support these identification types:

How It Works (Lifecycle)

Here is the complete flow from setup to invoice submission:

Step 1: Generate CSR & Private Key

Do this once when setting up your system with ZATCA.

What happens next:

1. Log in to the ZATCA Fatoora Portal
2. Register your device — ZATCA gives you an OTP
3. Use the OTP to request a compliance certificate (see Step 2)

Important: The OTP, compliance certificate and production certificate must all come from the same environment. For simulation, generate the OTP from the Fatoora Simulation portal; sandbox/developer-portal credentials will be rejected with "You are not authorized to use this api endpoint".

Step 2: Get Your Certificate from ZATCA

Step 3: Create & Submit an Invoice

This is the main workflow you'll use for every invoice.

Simplified Tax Invoice (B2C)

Standard Tax Invoice (B2B)

The only difference from simplified is the invoice type — everything else is the same:

Invoice Types

Summary

Transaction Flags (KSA-2)

The name attribute is NNPNESB: the subtype (01 standard, 02 simplified) followed by five flags. Set them with chainable methods, in any order:

Pass false to clear a flag (->export(false)). generateXml() rejects the combinations ZATCA forbids:

• an export invoice that is self-billed (BR-KSA-07)
• a simplified invoice flagged as export or self-billed (BR-KSA-31)
• an export invoice with a buyer VAT number (BR-KSA-46)
• a simplified summary invoice without a supply end date or buyer name (BR-KSA-71/72)

Supply Dates

The supply date (KSA-5) defaults to the issue date. Summary invoices also need a supply end date (KSA-24):

Prepayment Adjustment

To deduct an earlier prepayment invoice (386) from a final invoice, add it with addPrepayment(). Each prepayment becomes a zero-value invoice line that references it (§9.5). PrepaidAmount becomes the sum of taxable amount and VAT, and PayableAmount is reduced by it:

Credit & Debit Notes

Credit and debit notes must reference the original invoice using addBillingReference(). Payment means are optional but recommended.

Data Reference

InvoiceData — All Setters

SellerData — All Setters

BuyerData — All Setters

Same methods as SellerData. For simplified invoices, setVatNumber() is optional.

InvoiceLineData — All Setters

Rounding: amounts are rounded half-up to 2 decimals at each step (line net, line VAT, VAT per category, totals), as the standard requires. Unit prices and quantities keep their decimals.

Tip: Call calculateTotals() on each line item, then call calculateTotals() on the invoice. This auto-fills lineExtensionAmount, taxAmount, taxExclusiveAmount, taxInclusiveAmount, and all invoice-level totals.

See also: Line discounts (BG-27) & B2B/B2C buyer party — how a line discount becomes a valid cac:AllowanceCharge, and how the buyer party differs between Standard (B2B) and Simplified (B2C) invoices.

Zero-rated, Exempt & Out-of-scope Items

Every line is standard-rated (S) by default. Use setTaxCategory() for other VAT categories. Z, E and O lines are always taxed at 0% and need a ZATCA exemption reason code. The reason text is filled in from ZATCA's official wording, except for VATEX-SA-OOS, where you must supply your own text.

You can mix categories in one invoice. calculateTotals() builds one VAT breakdown entry (cac:TaxSubtotal) per category, rate and reason, and the XML includes it automatically. For VATEX-SA-EDU and VATEX-SA-HEA, ZATCA also requires the buyer's national ID (NAT).

A document-level allowance or charge uses the first line's category unless you set tax_category (and tax_percent for S):

Previous Invoice Hash (PIH) Chain

Every invoice references the hash of the previous invoice to create a tamper-proof chain:

Validation

validate() checks an invoice against the ZATCA business rules before anything is sent, and lists every problem at once. You don't have to wait for ZATCA to reject the invoice one error at a time.

• error: ZATCA rejects the invoice.
• warning: accepted, but probably not what you want (e.g. a credit note without a real reason).

Set 'validate' => true in the ZatcaManager config to validate automatically in processInvoice(). Errors then throw a ZatcaValidationException before signing or sending. Warnings never block.

What is checked:

Character limits (BR-KSA-F-06) come from ZATCA's separate Data Dictionary and are not checked.

Error Handling

All exceptions extend ZatcaException and provide a getContext() method with structured error details.

Package Structure

Testing

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

Acknowledgments

This package includes code and inspiration from:

• php-zatca-xml by Saleh7 — XML generation and ZATCA compliance logic.

License

This package is open-sourced software licensed under the MIT license.

Support

• Email: [email protected]
• GitHub Issues: Create an issue

Changelog

See CHANGELOG.md for version history.