ربط Moyasar مع زاتكا

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

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

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

payment_paid ('a payment is successfully processed'). Others: payment_failed (spelled payment_faild in one page), payment_refunded, payment_voided, payment_authorized, payment_captured, payment_verified

التسجيل

dashboard.moyasar.com > Settings > Webhooks > Add Webhook: HTTPS endpoint, Secret Token, HTTP method, events. A new webhook is Unverified: enter the 6-digit code from the webhook_verification event under Verify Webhook (expires in 30 minutes). API: Create Webhook

التحقق إن الطلب جاي من Moyasar

No signature header: every event body carries secret_token (the secret you set); compare it on your server

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

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

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

الكود

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

<?php
// Moyasar webhook: the body carries the secret_token you set in the dashboard.
$event = json_decode(file_get_contents('php://input'), true);
if (!hash_equals(getenv('MOYASAR_WEBHOOK_SECRET'), (string) ($event['secret_token'] ?? ''))) {
    http_response_code(401); exit;
}
http_response_code(200);
if ($event['type'] !== 'payment_paid') exit;
$payment = $event['data'];                    // amount is in halalas
$orderId = $payment['metadata']['order_id'];  // set when you created the payment
$items = load_order_items($orderId);          // your lines: name, quantity, price before VAT
matheel_invoice($items);

ملاحظات

Whether the amount includes VAT is the merchant's choice, since Moyasar charges whatever amount you send. metadata.order_id is an example key: Moyasar documents metadata as arbitrary string pairs, so use whatever key you set. An unofficial npm package verifies an x-moyasar-signature header, but the official docs only describe secret_token. Record processed event ids (event.id) so a repeated delivery does not file twice (Moyasar's retry policy was not checked). load_order_items is your own function, not Matheel's.

أسئلة شائعة

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

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

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

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

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

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

المصادر الرسمية: docs.moyasar.com/api/other/webhooks/webhook-reference · docs.moyasar.com/guides/dashboard/setting-up-webhooks · docs.moyasar.com/api/metadata · docs.moyasar.com/llms-full.txt

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

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

ابدأ الأسعار