ZATCA e-invoicing for HyperPay
HyperPay (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
Webhook notification type PAYMENT; paid when payload.result.code matches the 'successfully processed' regex and payload.paymentType is DB (debit) or CP (capture of a PA)
Registering it
HyperPay portal > Administration > Webhooks: URL, Types (PAYMENTS), Fields (ALL or NON_CUSTOMER_DATA), Secret (64 hex chars), Wrapper (None or JSON), failure e-mails. New webhooks are inactive until 'Click to Test' succeeds
Checking it came from HyperPay
Body encrypted with AES-256-GCM (no padding), key = the 64-hex secret; IV in header X-Initialization-Vector (hex), tag in X-Authentication-Tag (hex), body hex (or {"encryptedBody": ...} with the JSON wrapper). A successful decrypt with the tag is the authentication
Amount and lines
- Amount:
payload.amount (string, e.g. "92.00"), payload.currency - Lines:
none; use your own order - Customer email:
payload.customer.email (only when Fields = ALL)
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
// HyperPay: hex body encrypted with AES-256-GCM; IV and tag come in headers.
$key = hex2bin(getenv('HYPERPAY_WEBHOOK_SECRET'));
$iv = hex2bin($_SERVER['HTTP_X_INITIALIZATION_VECTOR'] ?? '');
$tag = hex2bin($_SERVER['HTTP_X_AUTHENTICATION_TAG'] ?? '');
$body = hex2bin(trim(file_get_contents('php://input'))); // Wrapper: None
$json = openssl_decrypt($body, 'aes-256-gcm', $key, OPENSSL_RAW_DATA, $iv, $tag);
if ($json === false) { http_response_code(401); exit; } // tag check failed
http_response_code(200);
$n = json_decode($json, true);
$p = $n['payload'];
$ok = preg_match('/^(000\.000\.|000\.100\.1|000\.[36]|000\.400\.[1][12]0|000\.500\.)/', $p['result']['code']);
if ($n['type'] !== 'PAYMENT' || !$ok || !in_array($p['paymentType'], ['DB', 'CP'], true)) exit;
$items = load_order_items($p['merchantTransactionId'] ?? $p['id']); // your lines, price before VAT
matheel_invoice($items);
Notes
The decryption call matches HyperPay's PHP sample (openssl_decrypt with aes-256-gcm, OPENSSL_RAW_DATA, iv, tag; PHP 7.1+). The success regex is the 'Successfully processed transactions' one from resultCodes, with the dots escaped. merchantTransactionId is a documented API parameter but is not in the webhook sample payload; whether it is echoed there is unknown. Payment types per the parameters page: DB = Debit, PA = Preauthorization, CP = Capture.
FAQ
Does HyperPay file invoices with ZATCA by itself?
HyperPay 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.