ZATCA e-invoicing for Telr

By Matheel · Updated

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

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.

Official sources: docs.telr.com/reference/webhook

Try it now on the developer sandbox

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

Start Pricing