ZATCA e-invoicing for PayTabs
PayTabs (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
Server-to-server callback / IPN (POST, JSON) after each transaction; paid when payment_result.response_status = 'A' ('Only (A) can be considered a successful transaction')
Registering it
Per transaction: 'callback' URL in the payment request. Account-wide: merchant Dashboard > Developers > Payment Notification > Configuration (types Default Web / Basic Web / SendGrid / Preflight SDK). The URL must be public HTTPS, or the IPN body arrives empty
Checking it came from PayTabs
Custom header 'Signature' = hex HMAC-SHA256 of the entire raw body, keyed with the profile Server Key (PayLinks / dashboard invoices: a default signature key you set). Compare with hash_equals
Amount and lines
- Amount:
cart_amount + cart_currency (what you requested); tran_total + tran_currency (what was charged) - Lines:
none (cart_description only); use your own order via cart_id - Customer email:
customer_details.email
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
// PayTabs callback/IPN: header Signature = HMAC-SHA256(raw body, profile Server Key).
$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_SIGNATURE'] ?? '';
if (!hash_equals(hash_hmac('sha256', $raw, getenv('PAYTABS_SERVER_KEY')), $sig)) {
http_response_code(401); exit;
}
http_response_code(200);
$t = json_decode($raw, true);
if (($t['payment_result']['response_status'] ?? '') !== 'A') exit; // only A is success
$items = load_order_items($t['cart_id']); // your lines: name, quantity, price before VAT
matheel_invoice($items);
Notes
The support article calls the header 'a custom header Signature' but doesn't spell its exact name in a sample, so log one real request to confirm it. The callback sample's top-level keys are tran_ref, merchant_id, profile_id, cart_id, cart_description, cart_currency, cart_amount, tran_currency, tran_total, tran_type, tran_class, customer_details, shipping_details, payment_result, payment_info and ipn_trace. If you use auth/capture, also check tran_type: whether an Auth also reports A was not confirmed in the docs. The browser return URL uses a different, form-encoded scheme (respStatus, a signature field in the body) and is not the IPN.
FAQ
Does PayTabs file invoices with ZATCA by itself?
PayTabs 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.