ZATCA e-invoicing for Moyasar

By Matheel · Updated

Moyasar (payment gateway) 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.

The event to listen to

payment_paid ('a payment is successfully processed'). Others: payment_failed (spelled payment_faild in one page), payment_refunded, payment_voided, payment_authorized, payment_captured, payment_verified

Registering it

dashboard.moyasar.com > Settings > Webhooks > Add Webhook: HTTPS endpoint, Secret Token, HTTP method, events. A new webhook is Unverified: enter the 6-digit code from the webhook_verification event under Verify Webhook (expires in 30 minutes). API: Create Webhook

Checking it came from Moyasar

No signature header: every event body carries secret_token (the secret you set); compare it on your server

Amount and lines

Payment gateways send no order lines: the code loads them from your own order by its reference (load_order_items is your function, not Matheel’s).

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
// Moyasar webhook: the body carries the secret_token you set in the dashboard.
$event = json_decode(file_get_contents('php://input'), true);
if (!hash_equals(getenv('MOYASAR_WEBHOOK_SECRET'), (string) ($event['secret_token'] ?? ''))) {
    http_response_code(401); exit;
}
http_response_code(200);
if ($event['type'] !== 'payment_paid') exit;
$payment = $event['data'];                    // amount is in halalas
$orderId = $payment['metadata']['order_id'];  // set when you created the payment
$items = load_order_items($orderId);          // your lines: name, quantity, price before VAT
matheel_invoice($items);

Notes

Whether the amount includes VAT is the merchant's choice, since Moyasar charges whatever amount you send. metadata.order_id is an example key: Moyasar documents metadata as arbitrary string pairs, so use whatever key you set. An unofficial npm package verifies an x-moyasar-signature header, but the official docs only describe secret_token. Record processed event ids (event.id) so a repeated delivery does not file twice (Moyasar's retry policy was not checked). load_order_items is your own function, not Matheel's.

FAQ

Does Moyasar file invoices with ZATCA by itself?

Moyasar is a payment gateway. 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.moyasar.com/api/other/webhooks/webhook-reference · docs.moyasar.com/guides/dashboard/setting-up-webhooks · docs.moyasar.com/api/metadata · docs.moyasar.com/llms-full.txt

Try it now on the developer sandbox

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

Start Pricing