matheel / matheel-php
Official client for the Matheel ZATCA Phase 2 e-invoicing API (Saudi Arabia, Fatoora): file invoices with a device token, decode the QR, verify callbacks.
Requires
- php: >=7.4
- ext-curl: *
- ext-json: *
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Official PHP client for Matheel, the ZATCA (Fatoora) Phase 2 e-invoicing API for Saudi
Arabia. One call signs the invoice, files it with ZATCA (reporting or clearance) and returns ZATCA's answer, the legal
XML, the QR and a bilingual PDF. PHP 7.4+, needs only ext-curl and ext-json.
composer require matheel/matheel-php
use Matheel\Matheel; $matheel = new Matheel(getenv('MATHEEL_KEY') ?: null); // no key needed on the sandbox // Try it now: the keyless sandbox files as Matheel's shared test taxpayer. $res = $matheel->fileInvoice([ 'environment' => 'sandbox', 'pdf' => true, 'invoice' => ['type' => 'simplified', 'line_items' => [['name' => 'Iqama renewal service', 'quantity' => 1, 'price' => '100.00']]], ]); $res['status']; // "reported" base64_decode($res['pdf']); // the PDF/A-3 invoice
After a payment: fileWithStore
Register the device once (onboard, or an activationLink for a merchant), keep its device_token in one database
row, and file every paid order through fileWithStore. The token carries the invoice chain (counter and hash), so
invoices of one device must be filed one after another: read and write the token under a row lock.
// CREATE TABLE matheel_device (id INT PRIMARY KEY, token TEXT NOT NULL); final class DeviceRow implements Matheel\TokenStore { private $db; public function __construct(PDO $db) { $this->db = $db; } public function read(): string { return $this->db->query('SELECT token FROM matheel_device WHERE id = 1 FOR UPDATE')->fetchColumn(); } public function write(string $token): void { $this->db->prepare('UPDATE matheel_device SET token = ? WHERE id = 1')->execute([$token]); } } function invoice_order(PDO $db, Matheel $matheel, array $items): array { $db->beginTransaction(); try { $res = $matheel->fileWithStore(new DeviceRow($db), ['type' => 'simplified', 'line_items' => $items], ['pdf' => true]); $db->commit(); return $res; // save base64_decode($res['pdf']) and $res['invoice_xml'] with the order } catch (Throwable $e) { $db->rollBack(); // the old token stays valid throw $e; } }
Generate a UUID v4 once per business document (Matheel::uuid4()), store it with the order and pass it on every
attempt (['uuid' => $order->invoice_uuid]): that is what makes a retry safe. On 200 it writes the new token (a 200
without one throws invalid_response, status 0: resend). On 409 device_token_reused it writes the
latest_device_token from the error and sends the invoice again; on 409 filing_in_progress it waits Retry-After (at
most 10 s) and retries (3 times in all). Anything else leaves the token alone and throws Matheel\MatheelError
(status, body, errorCode); Matheel::classify($e) says what to do:
classify |
Errors | Do |
|---|---|---|
retryable |
network (status 0), invalid_response, 429, 5xx (504 filing_outcome_unknown, 503 zatca_unavailable), 409 previous_filing_unknown, 422 filing_failed |
Send the same request later: same uuid. A document ZATCA already accepted comes back as a 200 with "replayed": true, never filed twice. Resend an unanswered document before any newer one. |
permanent |
422 zatca_rejected, invalid, missing_fields, invalid_amount, validation_failed |
Fix the document; the token is unchanged. |
needs_attention |
401 invalid_api_key / invalid_csid, 402 production_plan_required, other 4xx |
Not the document's fault: keep it, alert a person, retry later. |
already_filed |
409 already_filed (error.counter, error.zatca_uuid) |
ZATCA accepted this uuid earlier: it is filed. Never resend it; keep the copy you saved then. |
Payments and refunds, done for you: PdoQueue
One table does the whole job a payment app needs: one invoice per payment (a gateway that notifies twice never makes two), credit notes for full or partial refunds linked to the original invoice, automatic retries when ZATCA or Matheel is down, and the legal XML kept in the database (plus XML and PDF copies on disk). MySQL, PostgreSQL or SQLite.
use Matheel\Matheel; use Matheel\PdoQueue; $queue = new PdoQueue($pdo, new Matheel(getenv('MATHEEL_KEY')), '/var/invoices'); $queue->install(); // once, and after every upgrade: creates or migrates the tables $queue->setToken($deviceToken); // once: the device_token from onboarding // After the gateway confirms a payment (Telr: verify it with Matheel::verifyTelr first): $row = $queue->invoice($tranRef, [ 'type' => 'simplified', 'prices_include_vat' => true, 'line_items' => [['name' => 'Renewal', 'quantity' => 1, 'amount' => '172.50']], ]); // $row['status']: reported | cleared | queued (filed later) | rejected (see $row['error']) | attention // $row['invoice_xml'] (the legal XML), $row['qr'], $row['number'], $row['uuid'], $row['pdf_path'], $row['xml_path'] // A full or partial refund: the refunded lines only (refused if the original was rejected). $queue->refund($refundRef, $tranRef, [['name' => 'Renewal', 'quantity' => 1, 'amount' => '172.50']], 'Customer refund'); // Cron, every 5 minutes: files what is still pending; alert a person on attention(). $queue->process(); foreach ($queue->attention() as $row) { /* email or log $row['ref'], $row['status'], $row['error'] */ }
- uuid. Each row gets its own UUID v4 when it is queued (or the
uuidyou put in the invoice), and every attempt sends it. A credit note gets its own uuid, number and totals:refund()drops the original'snumber,uuid,issued_at,subtotal,vat_amount,totalandcounter. - Statuses.
queued: filed by the nextprocess()with the same request.reported/cleared: accepted (a409 already_filedcounts too, see below).rejected: only forzatca_rejected,invalid,missing_fields,invalid_amountandvalidation_failed; fix the data and queue it again under a new reference.attention: a bad key or CSID (401) or no production plan (402); still retried byprocess(), never marked rejected. attention($stuckHours = 12)lists rows a person must look at: statusattention, rows stillqueuedafter 12 hours (simplified invoices must reach ZATCA within 24), and accepted rows with no saved XML.- Order and recovery. Filing runs under a lock on the device row; the new token and the row's answer commit in one
transaction, and the files on disk are written after commit (a full disk loses no token). An answer that never
arrived (network, 5xx, 409) stops the run: the next
process()resends that exact request first and gets ZATCA's stored answer back (replayed). A credit note waits for its original; rows refused before reaching ZATCA (503zatca_unavailable) do not hold up the rows after them.invoice()andrefund()file the new row at once only when nothing older is pending; otherwise cron files it in order. If ZATCA accepted a document whose answer was lost and the chain has moved on, the server answers409 already_filed: the row becomesreportedwith ZATCA's uuid and, having no XML, shows up inattention(). - Transactions. Give the queue a connection with no open transaction (it throws
LogicExceptionotherwise): it commits its own work, so a rollback of yours can never undo a filing ZATCA already has. Database errors propagate and roll back; only API answers are recorded on the row.
Simplified invoices may be reported up to 24 hours after issue, so an outage only delays them. Tested on PHP 7.4 and
8.3, SQLite and PostgreSQL, against ZATCA's developer sandbox (invoice, duplicate notification, replayed answer, stale
token, partial refund): php tests/queue.php (MATHEEL_OFFLINE=1 for the offline part only).
API
new Matheel(?string $key = null, string $baseUrl = 'https://matheel.app', int $timeout = 60) |
The client. |
fileInvoice(['deviceToken' => …, 'invoice' => […], 'pdf' => true]) |
POST /api/v1/invoices. Other keys (environment, seller, csid, mode) pass through. |
fileWithStore(TokenStore $store, array $invoice, ['uuid' => …, 'pdf' => true, 'retries' => 3]) |
The safe chain helper above. |
Matheel::classify(MatheelError $e) |
retryable, permanent, needs_attention or already_filed (table above). |
Matheel::uuid4() |
A random UUID v4 for a new document. |
onboard(['environment' => …, 'seller' => […], 'device' => […], 'otp' => …]) |
POST /api/v1/onboarding, returns device_token. |
activationLink(['environment' => …, 'reference' => …, 'callbackUrl' => …, 'expiresInDays' => …, 'maxDevices' => …]) |
POST /api/v1/onboarding/links. |
Matheel::decodeQr($qr) |
QrData with sellerName, vatNumber, timestamp, total, vatAmount, invoiceHash, signature, publicKey, certificateSignature (tags 8 and 9 as base64). |
Matheel::verifyActivationCallback(file_get_contents('php://input'), $_SERVER['HTTP_X_MATHEEL_SIGNATURE'] ?? null, $callbackSecret) |
Checks an activation callback (HMAC-SHA256, hash_equals). |
Matheel::verifyTelr($_POST, $telrSecret) |
Checks Telr's tran_check on a transaction advice. |
Every non-200 answer throws MatheelError; errorCode is the API's error code (device_token_reused,
sandbox_rate_limited, invalid_device_token, …), zatca_rejected when ZATCA's errors are in the body, or
network_error (status 0); retryAfter holds the Retry-After seconds when sent. Keep the key and the device token on your server, never in an app.
Tests: php tests/run.php (one live sandbox filing; MATHEEL_OFFLINE=1 skips it).
Docs: https://matheel.app/en/docs · PHP guide: https://matheel.app/en/zatca-integration/php · API reference for agents: https://matheel.app/llms.txt
عربي
مكتبة ماثل الرسمية لـ PHP: أرسل فاتورة زاتكا (المرحلة الثانية) بطلب واحد، ويرجع لك رد الهيئة والـ XML والـ QR والـ PDF.
بعد الدفع استخدم fileWithStore مع قفل صف الجهاز في قاعدة بياناتك (SELECT … FOR UPDATE)، وهي تحفظ device_token
الجديد بعد كل فاتورة مقبولة. ولّد uuid واحد لكل فاتورة واحفظه وأرسله في كل محاولة، فإعادة الإرسال آمنة ولا تُسجَّل الفاتورة مرتين. بيئة التجربة ما تحتاج مفتاح. الدليل: matheel.app/rabt