ZATCA e-invoicing for Zid

By Matheel · Updated

Zid (online store) tells you when an order is paid; Matheel turns that payment into a ZATCA invoice, filed and accepted, with a bilingual PDF and the QR.

Before you connect: Zid says invoices in Zid and Zid Cashier meet ZATCA and Fatoora requirements, so check your store dashboard for whether your invoices already reach ZATCA, and don't pay twice. Matheel helps when you have another system or sales channel outside Zid, or want your device and invoice chain in your own hands.

The event to listen to

order.payment_status.update: 'Triggered when an order's payment status changes to paid or unpaid' (unpaid covers pending, refunded, voided). The payload uses the Order schema

Registering it

Merchant API: POST https://api.zid.sa/v1/managers/webhooks with headers Authorization (partner token) and X-Manager-Token; body {event, target_url, original_id, conditions?, username?, password?}. conditions only work for order.create and order.status.update

Checking it came from Zid

HTTP Basic: if the webhook was created with username/password, Zid sends Authorization: Basic base64(username:password). No HMAC signature is documented

Amount and lines

If the amount includes VAT (it usually does), send it as is with "prices_include_vat": true.

The code

It receives the event, verifies it and calls matheel_invoice(items): the ready function that locks the device row, files the invoice and saves the new token.

<?php
// Zid sends Basic auth built from the username/password you gave when creating the webhook.
$expected = 'Basic ' . base64_encode(getenv('ZID_HOOK_USER') . ':' . getenv('ZID_HOOK_PASS'));
if (!hash_equals($expected, $_SERVER['HTTP_AUTHORIZATION'] ?? '')) { http_response_code(401); exit; }
$o = json_decode(file_get_contents('php://input'), true);
http_response_code(200);
if (($o['payment_status'] ?? '') !== 'paid') exit;
$items = array_map(fn($p) => [
    'name'     => $p['name'],
    'quantity' => (string) $p['quantity'],
    // discounted_total includes VAT: remove it and divide by quantity.
    'price'    => number_format($p['discounted_total'] / $p['quantity'] / (1 + $p['tax_percentage']), 2, '.', ''),
], $o['products']);
matheel_invoice($items);

Notes

Field names and their meanings come from the View Order API (the webhook page says its payload is the Order schema, but the schema did not render). Unknown: whether the order sits at the payload root or under a wrapper key, so log one real delivery first. payment_status values documented on View Order: pending, paid, failed, refunded. Some PHP hosts drop the Authorization header before it reaches $_SERVER. The webhook overview documents no signature or secret beyond Basic auth.

FAQ

Does Zid file invoices with ZATCA by itself?

Zid is a online store. It reaches ZATCA through a service like Matheel: each successful payment becomes an invoice filed with ZATCA.

Do I have to change my prices for VAT?

No. Send the amount the customer paid with "prices_include_vat": true; Matheel backs the VAT out and keeps the amount due equal to what was paid.

What if two payments arrive in the same second?

A device's invoices go one after another. Lock the device row while filing (the ready function does), and Matheel refuses a stale device token with 409 so the chain never forks.

Official sources: docs.zid.sa/webhooks · docs.zid.sa/webhook-events-order.md · docs.zid.sa/create-a-webhook.md · docs.zid.sa/view-order-12479054e0.md

Try it now on the developer sandbox

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

Start Pricing