ZATCA e-invoicing for WooCommerce
WooCommerce (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.
There is a ready plugin: download Matheel for WooCommerce and activate it; you do not need the code below, which is for building it yourself.
The event to listen to
woocommerce_payment_complete (PHP action, args: $order_id, $transaction_id). Outside WordPress: webhook topic order.updated, then check status processing/completed and date_paid
Registering it
In-site: add_action('woocommerce_payment_complete', ...) in a small plugin. External server: WooCommerce > Settings > Advanced > Webhooks > Add webhook (name, status, topic, delivery URL, secret)
Checking it came from WooCommerce
In-site action: none needed (runs inside WordPress). Webhook: header X-WC-Webhook-Signature = base64 HMAC-SHA256 of the payload, keyed with the webhook secret (defaults to the API user's consumer secret if blank)
Amount and lines
- Amount:
REST/webhook order: total (grand total), total_tax; line_items[].total (line total after discounts) and line_items[].total_tax. PHP: $order->get_item_total($item, false) = unit price after discounts, excluding tax - Lines:
PHP: $order->get_items() -> $item->get_name(), $item->get_quantity(). REST/webhook: line_items[].name, line_items[].quantity - Customer email:
billing.email (PHP: $order->get_billing_email())
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
// Small plugin: fires once a gateway marks the order paid (WC_Order::payment_complete).
add_action('woocommerce_payment_complete', function ($order_id) {
$order = wc_get_order($order_id);
$items = [];
foreach ($order->get_items() as $item) {
$items[] = [
'name' => $item->get_name(),
'quantity' => (string) $item->get_quantity(),
// Unit price after discounts, without tax ($inc_tax = false).
'price' => number_format($order->get_item_total($item, false, true), 2, '.', ''),
];
}
$res = matheel_invoice($items);
$order->add_order_note('Matheel: ' . $res['status']);
});
Notes
prices_include_tax (REST, read-only) says whether shop prices were entered with tax; get_item_total(..., false) returns the price without tax either way. get_items() returns product lines only: shipping_lines and fee_lines are separate, so add them as their own items if the customer paid for them. The REST docs list core topics order.created/order.updated/order.deleted and custom action.<hook> topics; there is no dedicated 'order paid' topic. Offline gateways (bank transfer, cheque, COD) may never call payment_complete (unverified): for them hook the order status change instead. The webhook docs page does not state the header or algorithm; they come from the REST API docs.
FAQ
Does WooCommerce file invoices with ZATCA by itself?
WooCommerce 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.