ZATCA e-invoicing for Salla
Salla (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: Salla offers e-invoicing services to its merchants, 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 Salla, or want your device and invoice chain in your own hands.
Salla issues its own tax invoice when an order completes. Check whether it is integrated with ZATCA for Phase 2 before adding Matheel, so one order never gets two invoices.
The event to listen to
order.payment.updated ('triggered when an order payment has been updated'). Salla has no dedicated 'order paid' event; order.created and order.status.updated are the alternatives
Registering it
Salla Partners portal > My Apps > your app > App Scope: Webhooks 'Read and Write' > Webhooks/Notifications section: add URL and Store Events. Merchant API alternative: Register Webhook endpoint (docs.salla.dev/webhooks/subscribe)
Checking it came from Salla
Signature strategy (default for Partner apps): headers X-Salla-Security-Strategy: Signature and X-Salla-Signature = hex HMAC-SHA256 of the request body with the webhook secret. Token strategy: the token itself in the Authorization header
Amount and lines
- Amount:
data.amounts.total.amount, data.amounts.tax.amount; items[].amounts.price_without_tax.amount, items[].amounts.tax.amount, items[].amounts.total.amount - Lines:
data.items[].name, data.items[].quantity - Customer email:
data.customer.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
// Salla webhook (Signature strategy): X-Salla-Signature = hex HMAC-SHA256 of the raw body.
$raw = file_get_contents('php://input');
$mine = hash_hmac('sha256', $raw, getenv('SALLA_WEBHOOK_SECRET'));
if (!hash_equals($mine, $_SERVER['HTTP_X_SALLA_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
$e = json_decode($raw, true);
http_response_code(200);
$o = $e['data'];
// Skip orders still waiting for payment (e.g. bank transfer not confirmed yet).
if ($e['event'] !== 'order.payment.updated' || $o['is_pending_payment']) exit;
$items = array_map(fn($i) => [
'name' => $i['name'],
'quantity' => (string) $i['quantity'],
'price' => number_format($i['amounts']['price_without_tax']['amount'], 2, '.', ''),
], $o['items']);
matheel_invoice($items);
Notes
Unconfirmed: (1) whether order.payment.updated fires exactly once when payment is confirmed; (2) what is_pending_payment means (it appears in the sample payloads, but its schema tab did not render); (3) whether items[].amounts.price_without_tax is per unit or per line (every sample has quantity 1). Salla's own Node sample hashes JSON.stringify(req.body), which can differ from the raw bytes; its PHP sample hashes the raw body, as here. The docs call the hash 64 characters for Signature and 32 for Token; that is inconsistent. Salla also has an invoice.created event ('Tax Invoice' with a qr_code field, fired when the order is completed or restored), so check whether the store already issues ZATCA invoices through Salla before adding Matheel.
FAQ
Does Salla file invoices with ZATCA by itself?
Salla issues its own tax invoice when an order completes. Check whether it is integrated with ZATCA for Phase 2 before adding Matheel, so one order never gets two invoices.
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.