Harden Paymob integration with 4-tier credential fallback

Credential resolution order: academy system_settings → current_academy
setting → config/services.php → env variable. Callback endpoint now
resolves academy from the payment record itself (no auth context needed).
Failed payments are explicitly marked with failure reason. Added HTTP
timeouts to all Paymob API calls.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.env.example

@@ -68,4 +68,10 @@ ATTENDANCE_MIN_RATE_PERCENT=75
 # This value is NOT editable from the admin panel — only via this env variable
 PLATFORM_SERVICE_FEE_PERCENT=3
 
+# Paymob Payment Gateway (optional — also configurable per-academy in system_settings)
+PAYMOB_API_KEY=
+PAYMOB_INTEGRATION_ID=
+PAYMOB_IFRAME_ID=
+PAYMOB_HMAC_SECRET=
+
 VITE_APP_NAME="${APP_NAME}"

app/Http/Controllers/Api/V1/PaymentController.php

@@ -14,21 +14,22 @@
 
 class PaymentController extends Controller
 {
-    public function initiate(Request $request, PaymobService $paymobService): JsonResponse
+    public function initiate(Request $request): JsonResponse
     {
         $request->validate([
             'invoice_uuid' => 'required|string',
         ]);
 
+        $user = $request->user();
+        $paymobService = new PaymobService($user->academy_id);
+
         if (!$paymobService->isConfigured()) {
             return response()->json([
                 'error' => 'payment_not_configured',
-                'message' => 'الدفع الإلكتروني غير مفعل حالياً',
+                'message' => 'الدفع الإلكتروني غير مفعل حالياً، يرجى التواصل مع الإدارة',
             ], 503);
         }
 
-        $user = $request->user();
-
         $invoice = Invoice::where('uuid', $request->invoice_uuid)
             ->whereIn('status', ['sent', 'partially_paid', 'overdue'])
             ->where('balance_due', '>', 0)
@@ -44,7 +45,6 @@ public function initiate(Request $request, PaymobService $paymobService): JsonRe
         try {
             $result = $paymobService->createPaymentIntention($invoice, $user);
 
-            // Create pending payment record
             Payment::create([
                 'academy_id' => $invoice->academy_id,
                 'branch_id' => $invoice->branch_id ?? null,
@@ -61,16 +61,16 @@ public function initiate(Request $request, PaymobService $paymobService): JsonRe
                 'gateway_data' => [
                     'provider' => 'paymob',
                     'paymob_order_id' => $result['order_id'],
-                    'payment_key' => substr($result['payment_key'], 0, 20) . '...',
                 ],
                 'created_by' => $user->id,
             ]);
 
             return response()->json([
+                'payment_url' => $result['iframe_url'],
                 'payment_key' => $result['payment_key'],
-                'iframe_url' => $result['iframe_url'],
                 'order_id' => $result['order_id'],
                 'amount' => $invoice->balance_due,
+                'amount_display' => number_format($invoice->balance_due / 100, 2) . ' ج.م',
             ]);
         } catch (\Throwable $e) {
             Log::error('[Paymob] Payment initiation failed', [
@@ -85,26 +85,46 @@ public function initiate(Request $request, PaymobService $paymobService): JsonRe
         }
     }
 
-    public function callback(Request $request, PaymobService $paymobService): JsonResponse
+    public function callback(Request $request): JsonResponse
     {
         $data = $request->all();
 
-        Log::info('[Paymob] Callback received', ['data' => $data]);
+        Log::info('[Paymob] Callback received', ['keys' => array_keys($data)]);
 
-        // Extract transaction data from nested structure
+        // Paymob sends data in either flat format or nested under 'obj'
         $transactionData = $data['obj'] ?? $data;
+        $orderId = $transactionData['order'] ?? ($transactionData['order']['id'] ?? null);
+
+        if (!$orderId) {
+            Log::warning('[Paymob] Callback missing order reference');
+            return response()->json(['status' => 'missing_order'], 400);
+        }
+
+        // Find the payment to determine which academy's HMAC to use
+        $payment = Payment::withoutGlobalScope('academy')
+            ->where('status', PaymentStatus::Pending)
+            ->whereJsonContains('gateway_data->paymob_order_id', (string) $orderId)
+            ->first();
+
+        if (!$payment) {
+            Log::warning('[Paymob] No pending payment for callback order', ['order_id' => $orderId]);
+            return response()->json(['status' => 'no_payment_found'], 404);
+        }
+
+        // Resolve credentials for the payment's academy
+        $paymobService = PaymobService::forAcademy($payment->academy_id);
 
         if (!$paymobService->verifyCallback($transactionData)) {
-            Log::warning('[Paymob] HMAC verification failed', $data);
+            Log::warning('[Paymob] HMAC verification failed', ['order_id' => $orderId]);
             return response()->json(['status' => 'invalid_hmac'], 400);
         }
 
-        $payment = $paymobService->processSuccessfulPayment($transactionData);
+        $processed = $paymobService->processCallback($transactionData);
 
-        if ($payment) {
-            return response()->json(['status' => 'processed', 'payment_id' => $payment->id]);
+        if ($processed) {
+            return response()->json(['status' => 'processed', 'payment_id' => $processed->id]);
         }
 
-        return response()->json(['status' => 'ignored']);
+        return response()->json(['status' => 'not_processed']);
     }
 }

config/services.php

@@ -47,4 +47,11 @@
         'key' => env('MESSAGING_HUB_KEY', ''),
     ],
 
+    'paymob' => [
+        'paymob_api_key' => env('PAYMOB_API_KEY'),
+        'paymob_integration_id' => env('PAYMOB_INTEGRATION_ID'),
+        'paymob_iframe_id' => env('PAYMOB_IFRAME_ID'),
+        'paymob_hmac_secret' => env('PAYMOB_HMAC_SECRET'),
+    ],
+
 ];