ZATCA e-invoicing for Telr
Telr (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.
No code: a ready n8n template verifies Telr’s signature and files the invoice for every successful payment (steps in the docs).
The event to listen to
Transaction advice (HTTP POST, form fields tran_*) to a pre-configured URL; paid when tran_status = 'A' (H = authorised but on hold)
Registering it
Telr Merchant Administration System > 'Payment Page' or 'Security' menu > 'Transaction advice': URL, transaction types, optionally 'Only include authorised transactions (status A or H)'
Checking it came from Telr
Field tran_check = SHA1 of secret:tran_store:tran_type:tran_class:tran_test:tran_ref:tran_prevref:tran_firstref[:tran_order]:tran_currency:tran_amount:tran_cartid:tran_desc:tran_status:tran_authcode:tran_authmessage (trimmed values, case-insensitive compare). tran_order only when Telr support has enabled it
Amount and lines
- Amount:
tran_amount + tran_currency - Lines:
none; use your own order via tran_cartid - Customer email:
bill_email (covered by its own bill_check hash)
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
// Telr transaction advice: form POST, verified by the SHA1 tran_check field.
$fields = ['tran_store','tran_type','tran_class','tran_test','tran_ref','tran_prevref','tran_firstref'];
if (isset($_POST['tran_order'])) $fields[] = 'tran_order'; // only if Telr enabled it
$fields = array_merge($fields, ['tran_currency','tran_amount','tran_cartid','tran_desc',
'tran_status','tran_authcode','tran_authmessage']);
$str = getenv('TELR_ADVICE_SECRET');
foreach ($fields as $f) $str .= ':' . trim($_POST[$f] ?? '');
if (strcasecmp(sha1($str), $_POST['tran_check'] ?? '') !== 0) { http_response_code(401); exit('Check mismatch'); }
http_response_code(200);
if ($_POST['tran_status'] !== 'A') exit; // A = authorised, H = on hold
$items = load_order_items($_POST['tran_cartid']); // your lines, price before VAT
matheel_invoice($items);
Notes
Confirmed earlier and re-read for this entry. The docs disagree on tran_order: the prose formula leaves it out and says to include it only when enabled, while the PHP sample always adds a ':' slot for it; the sketch follows the prose. Telr's own PHP sample compares against an undefined $hash_check instead of $check. Separate card_check and bill_check hashes cover the card_* and bill_* fields.
FAQ
Does Telr file invoices with ZATCA by itself?
Telr 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.