ربط Tap Payments مع زاتكا

من فريق ماثل · آخر تحديث

Tap Payments (بوابة دفع) يبلغك لما الطلب يندفع، وماثل يحوّل هالدفعة لفاتورة زاتكا مرسلة ومقبولة، مع PDF عربي وإنجليزي فيه رمز QR.

الحدث اللي تستمع له

POST to post.url with the charge object; success = status CAPTURED (as in the sample payload)

التسجيل

Per request: send "post": {"url": "https://your-server/tap/webhook"} in the Create Charge (or Authorize/Invoice) request

التحقق إن الطلب جاي من 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)

المبلغ والبنود

بوابات الدفع ما ترسل بنود الطلب: الكود يجيبها من طلبك أنت برقم الطلب (الدالة load_order_items من نظامك، مو من ماثل).

لو المبلغ شامل الضريبة (وهو الغالب)، أرسله زي ما هو مع "prices_include_vat": true.

الكود

يستقبل الحدث، يتحقق منه، ويستدعي matheel_invoice(items): الدالة الجاهزة اللي تقفل صف الجهاز وترسل الفاتورة وتحفظ المفتاح الجديد.

<?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);

ملاحظات

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.

أسئلة شائعة

هل Tap Payments يرسل الفواتير لزاتكا بنفسه؟

Tap Payments بوابة دفع، وربطه مع الهيئة يكون عن طريق خدمة مثل ماثل: كل دفعة ناجحة تتحول لفاتورة مرسلة للهيئة.

لازم أعدّل الأسعار عشان الضريبة؟

لا. أرسل المبلغ اللي دفعه العميل مع "prices_include_vat": true، وماثل يطلّع الضريبة ويخلّي المبلغ المستحق في الفاتورة نفس المدفوع.

وش يصير لو جت دفعتين بنفس الثانية؟

فواتير الجهاز تمشي ورا بعض. اقفل صف الجهاز وقت الإرسال (موجود في الدالة الجاهزة)، وماثل يرفض أي نسخة قديمة من مفتاح الجهاز بـ 409 عشان السلسلة ما تنكسر.

المصادر الرسمية: developers.tap.company/docs/webhook

جرّبه الحين على بيئة المطورين

بدون مفتاح ولا تسجيل: الرد رد الهيئة الحقيقي، ومعه الفاتورة PDF عربي وإنجليزي ورمز QR.

ابدأ الأسعار