ZATCA e-invoicing for Tap Payments

By Matheel · Updated

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

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.

Official sources: developers.tap.company/docs/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