ZATCA e-invoicing for Tap Payments
Tap Payments (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
POST to post.url with the charge object; success = status CAPTURED (as in the sample payload)
Registering it
Per request: send "post": {"url": "https://your-server/tap/webhook"} in the Create Charge (or Authorize/Invoice) request
Checking it came from Tap Payments
Header hashstring = hex HMAC-SHA256, keyed with your secret API key, of 'x_id'+id+'x_amount'+amount+'x_currency'+currency+'x_gateway_reference'+reference.gateway+'x_payment_reference'+reference.payment+'x_status'+status+'x_created'+transaction.created. Format the amount to the currency's decimals (2 for SAR, 3 for KWD/BHD/OMR/JOD)
Amount and lines
- Amount:
amount (decimal, e.g. 1.0 SAR); currency - Lines:
none in the charge; use your own order via reference.order (or metadata.udf1..) - Customer email:
customer.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
// Tap posts the charge to the post.url you sent when creating it.
$c = json_decode(file_get_contents('php://input'), true);
$amount = number_format($c['amount'], 2, '.', ''); // SAR: 2 decimals (KWD/BHD/OMR/JOD: 3)
$str = 'x_id' . $c['id'] . 'x_amount' . $amount . 'x_currency' . $c['currency']
. 'x_gateway_reference' . ($c['reference']['gateway'] ?? '')
. 'x_payment_reference' . $c['reference']['payment']
. 'x_status' . $c['status'] . 'x_created' . $c['transaction']['created'];
$mine = hash_hmac('sha256', $str, getenv('TAP_SECRET_KEY'));
if (!hash_equals($mine, $_SERVER['HTTP_HASHSTRING'] ?? '')) { http_response_code(401); exit; }
http_response_code(200);
if ($c['status'] !== 'CAPTURED') exit;
$items = load_order_items($c['reference']['order']); // your lines, price before VAT
matheel_invoice($items);
Notes
The page doesn't list all statuses; CAPTURED is the value in the charge sample. If reference.gateway is missing, the docs say to pass an empty value. The sample also has a 'hash' header; validation uses 'hashstring'. Invoices and authorizes use different hash fields (invoice: x_id, x_amount, x_currency, x_updated, x_status, x_created). The VAT treatment of amount is up to the merchant.
FAQ
Does Tap Payments file invoices with ZATCA by itself?
Tap Payments 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.