ZATCA e-invoicing for WooCommerce

By Matheel · Updated

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

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.

Official sources: developer.woocommerce.com/docs/best-practices/urls-and-routi · woocommerce.github.io/woocommerce-rest-api-docs/#webhooks · woocommerce.github.io/woocommerce-rest-api-docs/#order-prope · github.com/woocommerce/woocommerce/blob/trunk/plugins/woocom · github.com/woocommerce/woocommerce/blob/trunk/plugins/woocom

Try it now on the developer sandbox

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

Start Pricing