ZATCA e-invoicing in PHP

By Matheel · Updated

One HTTP request from PHP (cURL + PDO): Matheel builds the invoice, signs it, files it with ZATCA and returns ZATCA's answer, the legal XML and the PDF with the QR.

1. Try it now (no key)

// composer require matheel/matheel-php
require 'vendor/autoload.php';

$matheel = new Matheel\Matheel(getenv('MATHEEL_KEY') ?: null); // the sandbox needs no key
$res = $matheel->fileInvoice(['environment' => 'sandbox', 'pdf' => true, 'invoice' => [
    'type' => 'simplified', 'line_items' => [['name' => 'قهوة', 'quantity' => 2, 'price' => '50.00']]]]);
echo $res['status']; // reported, plus qr, pdf, invoice_xml
// After a payment: $matheel->fileWithStore($store, $invoice) keeps the device chain for you

2. The ready function, after payment

It locks the device row (so two payments at once never fork the chain), files the invoice with "pdf": true and saves the new device_token. Any non-200 rolls the transaction back and the old token stays valid.

<?php
// Call after the payment gateway confirms the payment. Returns Matheel's response (pdf, invoice_xml, qr…).
function matheel_invoice(PDO $db, array $items): array {
    $db->beginTransaction();
    // Row lock: two payments in the same second file one after the other, never on the same token.
    $token = $db->query("SELECT token FROM matheel_device WHERE id = 1 FOR UPDATE")->fetchColumn();
    $ch = curl_init("https://matheel.app/api/v1/invoices");
    curl_setopt_array($ch, [
        CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 60,
        CURLOPT_HTTPHEADER => ["Content-Type: application/json", "Authorization: Bearer " . getenv("MATHEEL_KEY")],
        CURLOPT_POSTFIELDS => json_encode(["device_token" => $token, "pdf" => true,
            "invoice" => ["type" => "simplified", "line_items" => $items]]),
    ]);
    $res = json_decode(curl_exec($ch), true);
    if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 200) { $db->rollBack(); throw new RuntimeException(json_encode($res)); }
    $db->prepare("UPDATE matheel_device SET token = ? WHERE id = 1")->execute([$res["device_token"]]);
    $db->commit();
    return $res;
}

// Example: after Telr says the payment is paid.
$res = matheel_invoice($db, [["name" => "تجديد إقامة", "quantity" => 1, "price" => "130.43"]]);
file_put_contents("invoices/{$orderId}.pdf", base64_decode($res["pdf"]));
file_put_contents("invoices/{$orderId}.xml", base64_decode($res["invoice_xml"]));

Or with the official Matheel library: composer require matheel/matheel-php; fileWithStore does the same: reads and saves the token through your store and retries on a 409 by itself.

3. For production

FAQ

Do I need a ZATCA library for PHP?

No. Matheel is a plain JSON API: one HTTP request. Signing, the XML, the certificate and filing with ZATCA all happen at Matheel. An official library exists if you want one: composer require matheel/matheel-php

Where do I keep the device token?

One row in your database (a matheel_device table). After every 200, save the new device_token in the same transaction.

Can I try before subscribing?

Yes, on the developer sandbox without a key: the request below returns ZATCA's real answer and the PDF.

Try it now on the developer sandbox

No key, no signup: a real ZATCA answer, with the bilingual PDF and the QR.

Start Pricing