مركز التوثيق ودليل المطورين الشامل

<?php
// 1. استقبال الـ Raw Payload والهيدر
$rawPayload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_PAYNIMB_SIGNATURE'] ?? '';
$webhookSecret = 'YOUR_WEBHOOK_SECRET'; // من لوحة تحكم التاجر

// 2. حساب التوقيع المتوقع باستخدام HMAC-SHA256
$expectedSignature = hash_hmac('sha256', $rawPayload, $webhookSecret);

// 3. مقارنة التوقيع في وقت ثابت لمنع Timing Attacks
if (!hash_equals($expectedSignature, $signature)) {
    http_response_code(400);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

// 4. معالجة الحدث بعد التأكد من صحة التوقيع 100%
$eventData = json_decode($rawPayload, true);
$eventName = $eventData['event'] ?? '';

switch ($eventName) {

    // ==========================================
    // 1. نجاح دفع فاتورة / طلب (One-time Payment)
    // ==========================================
    case 'payment.succeeded':
        $orderId       = $eventData['order_id'];        // معرف الطلب في متجرك (مثال: ORD-1002)
        $chargeId      = $eventData['charge_id'];       // معرف جلسة الدفع في Paynimb (ch_...)
        $transactionId = $eventData['transaction_id'];  // رقم المعاملة المرجعي (TXN-...)
        $amount        = (float)$eventData['amount'];   // المبلغ المدفوع (مثال: 49.99)
        $currency      = $eventData['currency'];        // عملة الدفع (USD, EGP, SAR...)
        $timestamp     = $eventData['timestamp'];       // وقت الدفع Unix timestamp

        // مثال الإجراء: تحديث حالة الطلب إلى "مدفوع" وشحن الرصيد أو إرسال المنتج للعميل
        // updateOrderStatus($orderId, 'paid', $transactionId);
        // sendOrderConfirmationEmail($orderId);
        break;

    // ==========================================
    // 2. فشل عملية دفع (Payment Failed)
    // ==========================================
    case 'payment.failed':
        $orderId       = $eventData['order_id'];
        $chargeId      = $eventData['charge_id'];
        $failureReason = $eventData['reason'] ?? 'رصيد غير كافٍ أو تم إلغاء العملية من العميل';

        // مثال الإجراء: إشعار العميل بفشل المحاولة وإتاحة رابط إعادة الدفع
        // markOrderAsFailed($orderId, $failureReason);
        // notifyCustomerPaymentFailed($orderId);
        break;

    // ==========================================
    // 3. اشتراك جديد / تجربة مجانية (New Subscription)
    // ==========================================
    case 'subscription.created':
        $subUuid       = $eventData['subscription_uuid'];  // معرف الاشتراك الفريد (sub_...)
        $planUuid      = $eventData['plan_uuid'];          // معرف الخطة (plan_...)
        $planTitle     = $eventData['plan_title'];         // اسم الباقة (مثال: Pro Monthly)
        $customerEmail = $eventData['customer_email'];      // بريد المشترك
        $amount        = (float)$eventData['amount'];
        $currency      = $eventData['currency'];
        $billingCycle  = $eventData['billing_cycle'];      // monthly, yearly, weekly
        $nextBilling   = $eventData['next_billing_date'];  // تاريخ التجديد القادم (2026-10-11)
        $isTrial       = !empty($eventData['is_trial']);   // هل هو في فترة تجريبية؟

        // مثال الإجراء: ترقية حساب العميل في موقعك لمنحه صلاحيات الباقة
        // grantUserSubscription($customerEmail, $planTitle, $nextBilling);
        break;

    // ==========================================
    // 4. تجديد اشتراك دوري بنجاح (Subscription Renewed)
    // ==========================================
    case 'subscription.renewed':
        $subUuid       = $eventData['subscription_uuid'];
        $amount        = (float)$eventData['amount'];
        $currency      = $eventData['currency'];
        $nextBilling   = $eventData['next_billing_date'];  // موعد الفاتورة القادمة الجديد
        $txnId         = $eventData['transaction_id'];

        // مثال الإجراء: تمديد صلاحية العميل لشهر أو سنة إضافية
        // extendSubscriptionAccess($subUuid, $nextBilling);
        break;

    // ==========================================
    // 5. إلغاء اشتراك أو إيقاف التجديد (Subscription Cancelled)
    // ==========================================
    case 'subscription.cancelled':
        $subUuid       = $eventData['subscription_uuid'];
        $cancelledAt   = $eventData['cancelled_at'];
        $graceUntil    = $eventData['access_until'] ?? null; // إتاحة الخدمة حتى نهاية المدة المدفوعة

        // مثال الإجراء: إيقاف الحساب أو تركه حتى انتهاء الفترة الحالية
        // revokeSubscriptionAccess($subUuid, $graceUntil);
        break;

    // ==========================================
    // 6. فشل تجديد الاشتراك (Past Due / Balance Failed)
    // ==========================================
    case 'subscription.past_due':
        $subUuid       = $eventData['subscription_uuid'];
        $customerEmail = $eventData['customer_email'];

        // مثال الإجراء: إرسال تنبيه بالبريد أو واتساب لتغذية رصيده لإعادة المحاولة
        // sendPaymentReminderNotice($customerEmail, $subUuid);
        break;

    // ==========================================
    // 7. فتح نزاع أو شكوى (Dispute / Chargeback Opened)
    // ==========================================
    case 'dispute.opened':
        $disputeId     = $eventData['dispute_id'];
        $transactionId = $eventData['transaction_id'];
        $reason        = $eventData['reason'];
        $claimAmount   = (float)$eventData['claim_amount'];

        // مثال الإجراء: تجميد الحساب أو الطلب مؤقتاً ومراجعة الشكوى
        // holdAccountOrDeliverables($transactionId, $reason);
        break;

    // ==========================================
    // 8. إرجاع أموال (Refund Processed)
    // ==========================================
    case 'refund.processed':
        $refundId      = $eventData['refund_id'];
        $orderId       = $eventData['order_id'];
        $refundAmount  = (float)$eventData['amount'];

        // مثال الإجراء: تسجيل الاسترجاع وإلغاء صلاحية المنتج الرقمي
        // recordRefundInDb($orderId, $refundAmount);
        break;

    default:
        // حدث غير معروف - تسجيله في السجلات للمعاينة
        // error_log("Unhandled Paynimb event: " . $eventName);
        break;
}

// 5. إرجاع كود 200 OK فوراً لتأكيد الاستلام ومنع إعادة الإرسال
http_response_code(200);
echo json_encode(['status' => 'acknowledged']);
exit;