KSA Tax Compliance

Laravel ZATCA E-Invoicing

Official-grade implementation of Saudi Arabia's ZATCA Phase 1 & 2 e-invoicing requirements, featuring automated XML generation and cryptographic stamping.

Open SourceLaravelFintechZATCA
Simplified tax invoiceINV-2026-0142
Seller
Acme Corp
VAT 300000000000003
Buyer
John Doe
No VAT number
ItemQtyPrice
Service A1100.00
VAT 15%15.00
Total115.00
Signed · ECDSA secp256k1Reporting
  1. UBL 2.1 XMLBuilt from your model
  2. C14NXML canonicalisation
  3. SHA-256Invoice hash
  4. ECDSA signaturesecp256k1 private key
  5. QR codeTLV, Base64
  6. ReportingSimplified invoices are reported to ZATCA
Illustrative invoice with the README's sample seller; the QR pattern is decorative, not a scannable code
Two phases

Phase 1 and phase 2 in one package

Phase 1 is local: build the XML and the QR code. Phase 2 sends the signed invoice to ZATCA, for clearance or for reporting.

Phase 1Local

Generate XML and QR codes locally

  • UBL 2.1 XML, correctly typed and schema-compliant
  • TLV, Base64-encoded QR code with all 9 tags
$invoice->generateZatcaXml();
Phase 2ZATCA API

Clearance and reporting through the API

  • Clearance for standard (B2B) invoices
  • Reporting for simplified (B2C) invoices
  • Signs automatically and picks the route
$invoice->submitToZatca();
Compliance flow

From your Invoice model to ZATCA

  1. Invoice modeluse HasZatca · then UBL 2.1 XML, QR code
  2. UBL 2.1 XMLPhase 1, local · then Sign
  3. QR codeTLV, Base64
  4. SignC14N, SHA-256, ECDSA · then Clearance, Reporting
  5. ClearanceStandard, B2B
  6. ReportingSimplified, B2C
Flow as described in the README
EnvironmentsSandbox · ZATCA Developer PortalProduction · Core API
Onboarding

Getting your device a CSID

The package ships Artisan commands for CSR generation, compliance checks and CSID onboarding.

  1. Configure the seller

    Seller name, VAT and CR numbers and your organisation details go in config/zatca.php or .env.

  2. Generate a CSR

    php artisan zatca:generate-csr --env=sandbox --save-db creates the CSR and a secp256k1 private key.

  3. Get an OTP

    Submit the CSR to the ZATCA portal to retrieve an OTP.

  4. Issue the CSID

    Zatca::client()->issueComplianceCsid() issues the compliance CSID; store it in your database.

The README notes that an activate-csid command is planned to store the CSID and secret automatically; until then, call Zatca::client()->issueComplianceCsid() and store the result yourself.

Code

Drop a trait on the Invoice you already have

app/Models/Invoice.php
use Hyderkamran\LaravelZatca\Traits\HasZatca;
use Hyderkamran\LaravelZatca\Enums\InvoiceType;
 
class Invoice extends Model
{
    use HasZatca;
 
    public function getZatcaInvoiceType(): InvoiceType
    {
        return $this->is_b2b ? InvoiceType::STANDARD : InvoiceType::SIMPLIFIED;
    }
 
    public function toZatcaSeller(): array
    {
        return [
            'name'       => 'Acme Corp',
            'vat_number' => '300000000000003',
            // ...
        ];
    }
 
    public function toZatcaBuyer(): array
    {
        return [
            'name'       => $this->customer->name,
            'vat_number' => $this->customer->vat_number,
        ];
    }
 
    public function toZatcaItems(): array
    {
        return $this->items->map(fn($item) => [
            'name'     => $item->name,
            'quantity' => $item->qty,
            'price'    => $item->price,
        ])->toArray();
    }
}
In the box

What Laravel ZATCA E-Invoicing covers

Phase 1 & 2 compliant · Cryptographic stamping · XML generation

  • Cryptography engine

    ECDSA secp256k1 private keys, C14N XML canonicalisation and SHA-256 hashing, built in.

  • E-invoicing

    Standard (B2B) and simplified (B2C) invoices.

  • XML generation

    UBL 2.1 XML, correctly typed and schema-compliant.

  • QR generation

    TLV Base64 encoding for the mandatory QR code, all 9 tags.

  • Phase 1 compliance

    Generate XML and QR codes locally.

  • Phase 2 compliance

    Clearance (standard) and reporting (simplified) API workflows.

  • Sandbox support

    Switch between the Developer Portal sandbox and the Core API.

  • CSID lifecycle

    Artisan commands for CSR generation, compliance checks and onboarding.

  • Eloquent integration

    A HasZatca trait for the Invoice model you already have.

Install

Install, publish, migrate

Laravel ZATCA E-Invoicing is maintained in the open, versioned semantically, and used in our own client projects — so fixes land upstream rather than in a private fork.

Terminal
composer require hyderkamran/laravel-zatca
 
php artisan vendor:publish --tag="zatca-config"
php artisan vendor:publish --tag="zatca-migrations"
 
# Creates the zatca_certificates and zatca_submissions tables
php artisan migrate

From the package README on GitHub

Packagehyderkamran/laravel-zatca
LicenceMIT
LanguagePHP / Laravel
RequiresPHP 8.1+Laravel 10 or 11ext-opensslext-simplexml
Maintained byApexlyTech, in the open on GitHub
View on GitHub

Issue invoices ZATCA will accept

Official-grade implementation of Saudi Arabia's ZATCA Phase 1 & 2 e-invoicing requirements, featuring automated XML generation and cryptographic stamping.