ربط PayTabs مع زاتكا
PayTabs (بوابة دفع) يبلغك لما الطلب يندفع، وماثل يحوّل هالدفعة لفاتورة زاتكا مرسلة ومقبولة، مع PDF عربي وإنجليزي فيه رمز QR.
الحدث اللي تستمع له
Server-to-server callback / IPN (POST, JSON) after each transaction; paid when payment_result.response_status = 'A' ('Only (A) can be considered a successful transaction')
التسجيل
Per transaction: 'callback' URL in the payment request. Account-wide: merchant Dashboard > Developers > Payment Notification > Configuration (types Default Web / Basic Web / SendGrid / Preflight SDK). The URL must be public HTTPS, or the IPN body arrives empty
التحقق إن الطلب جاي من PayTabs
Custom header 'Signature' = hex HMAC-SHA256 of the entire raw body, keyed with the profile Server Key (PayLinks / dashboard invoices: a default signature key you set). Compare with hash_equals
المبلغ والبنود
- المبلغ:
cart_amount + cart_currency (what you requested); tran_total + tran_currency (what was charged) - البنود:
none (cart_description only); use your own order via cart_id - إيميل العميل:
customer_details.email
بوابات الدفع ما ترسل بنود الطلب: الكود يجيبها من طلبك أنت برقم الطلب (الدالة load_order_items من نظامك، مو من ماثل).
لو المبلغ شامل الضريبة (وهو الغالب)، أرسله زي ما هو مع "prices_include_vat": true.
الكود
يستقبل الحدث، يتحقق منه، ويستدعي matheel_invoice(items): الدالة الجاهزة اللي تقفل صف الجهاز وترسل الفاتورة وتحفظ المفتاح الجديد.
<?php
// PayTabs callback/IPN: header Signature = HMAC-SHA256(raw body, profile Server Key).
$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_SIGNATURE'] ?? '';
if (!hash_equals(hash_hmac('sha256', $raw, getenv('PAYTABS_SERVER_KEY')), $sig)) {
http_response_code(401); exit;
}
http_response_code(200);
$t = json_decode($raw, true);
if (($t['payment_result']['response_status'] ?? '') !== 'A') exit; // only A is success
$items = load_order_items($t['cart_id']); // your lines: name, quantity, price before VAT
matheel_invoice($items);
ملاحظات
The support article calls the header 'a custom header Signature' but doesn't spell its exact name in a sample, so log one real request to confirm it. The callback sample's top-level keys are tran_ref, merchant_id, profile_id, cart_id, cart_description, cart_currency, cart_amount, tran_currency, tran_total, tran_type, tran_class, customer_details, shipping_details, payment_result, payment_info and ipn_trace. If you use auth/capture, also check tran_type: whether an Auth also reports A was not confirmed in the docs. The browser return URL uses a different, form-encoded scheme (respStatus, a signature field in the body) and is not the IPN.
أسئلة شائعة
هل PayTabs يرسل الفواتير لزاتكا بنفسه؟
PayTabs بوابة دفع، وربطه مع الهيئة يكون عن طريق خدمة مثل ماثل: كل دفعة ناجحة تتحول لفاتورة مرسلة للهيئة.
لازم أعدّل الأسعار عشان الضريبة؟
لا. أرسل المبلغ اللي دفعه العميل مع "prices_include_vat": true، وماثل يطلّع الضريبة ويخلّي المبلغ المستحق في الفاتورة نفس المدفوع.
وش يصير لو جت دفعتين بنفس الثانية؟
فواتير الجهاز تمشي ورا بعض. اقفل صف الجهاز وقت الإرسال (موجود في الدالة الجاهزة)، وماثل يرفض أي نسخة قديمة من مفتاح الجهاز بـ 409 عشان السلسلة ما تنكسر.