ربط HyperPay مع زاتكا

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

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

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

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)

التسجيل

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

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

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

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

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

الكود

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

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

ملاحظات

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.

أسئلة شائعة

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

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

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

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

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

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

المصادر الرسمية: hyperpay.docs.oppwa.com/tutorials/webhooks · hyperpay.docs.oppwa.com/reference/resultCodes · hyperpay.docs.oppwa.com/reference/parameters

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

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

ابدأ الأسعار