Complete Payment module: initiate/webhook/confirm/refund actions, Filament resources (T5.8-T5.13)

- InitiatePaymentAction + POST /api/v1/payments/{booking}/initiate - Generic KBZ webhook (POST /api/v1/webhooks/{method}/{encryptBookingId?}), signature verification per KBZ's real callback spec, PaymentGatewayInterface::handleWebhook() - ConfirmPaymentAction: idempotent confirmation, PaymentCompleted/PaymentFailed events, MarkBookingPaid listener - RefundBookingAction + POST /api/v1/bookings/{booking}/refund: partial refunds validated against remaining balance, RefundProcessed event, MarkBookingRefunded listener - CancelBookingAction now refunds confirmed bookings instead of rejecting; BookingPolicy::cancel requires process_refunds for confirmed bookings - PaymentPlugin + PaymentResource/RefundResource Filament admin UI (read-only payments, refund list + Process action) - Booking detail page now shows related payments - Fix CACHE_STORE mismatch (database -> redis) so tagged route caching works - CLAUDE.md: never run migrate:fresh/migrate:refresh/db:wipe on dev without being asked
2026-08-09 16:20:21 +07:00
parent 4737838021
commit d19a14a45e
55 changed files with 2547 additions and 29 deletions
@@ -0,0 +1,92 @@
+<?php
+
+namespace Modules\Payment\Http\Controllers;
+
+use Illuminate\Contracts\Encryption\DecryptException;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+use Illuminate\Routing\Controller;
+use Illuminate\Support\Facades\Crypt;
+use Illuminate\Support\Facades\Log;
+use Modules\Payment\Actions\ConfirmPaymentAction;
+use Modules\Payment\Enums\PaymentMethod;
+use Modules\Payment\Exceptions\InvalidWebhookSignatureException;
+use Modules\Payment\Factories\PaymentGatewayFactory;
+
+/**
+ * One inbound webhook route for every gateway, routed by PaymentMethod and
+ * resolved through PaymentGatewayFactory (T5.6) — mirrors bnf_event's
+ * `OrderController::paymentComplete`/`{method}` dispatch, but through the
+ * factory instead of a switch, so adding a gateway needs no controller
+ * change (domain.md §6).
+ */
+class PaymentWebhookController extends Controller
+{
+    public function __construct(
+        private PaymentGatewayFactory $gateways,
+        private ConfirmPaymentAction $confirmPaymentAction,
+    ) {}
+
+    public function handle(Request $request, PaymentMethod $method, ?string $encryptBookingId = null): Response
+    {
+        $payload = $request->all();
+
+        // Optional, mirrors bnf_event's `{encryptOrderId?}` — a redundant,
+        // signature-independent way to locate the booking directly from the
+        // URL (used by ConfirmPaymentAction, T5.10) alongside whatever
+        // order id the gateway's own signed payload carries. Never fatal if
+        // it's missing or fails to decrypt; the signature check is what
+        // actually authenticates this request.
+        $bookingId = $this->decryptBookingId($encryptBookingId);
+
+        try {
+            $result = $this->gateways->make($method)->handleWebhook($payload);
+        } catch (InvalidWebhookSignatureException $exception) {
+            // Raw payload persisted regardless of outcome (domain.md §6).
+            Log::warning('Payment webhook rejected: invalid signature', [
+                'gateway' => $method->value,
+                'booking_id' => $bookingId,
+                'payload' => $payload,
+            ]);
+
+            throw $exception;
+        }
+
+        Log::info('Payment webhook received', [
+            'gateway' => $method->value,
+            'booking_id' => $bookingId,
+            'status' => $result->status->value,
+            'gateway_transaction_id' => $result->gatewayTransactionId,
+            'payload' => $payload,
+        ]);
+
+        $payment = $result->gatewayTransactionId !== null
+            ? $this->confirmPaymentAction->handle($method, $result->gatewayTransactionId)
+            : null;
+
+        if ($payment === null) {
+            Log::warning('Payment webhook has no matching payment to confirm', [
+                'gateway' => $method->value,
+                'gateway_transaction_id' => $result->gatewayTransactionId,
+            ]);
+        }
+
+        // KBZ retries any delivery that doesn't get back this exact literal
+        // body — we acknowledge regardless of whether a matching payment
+        // was found, since retrying won't fix that mismatch.
+        return response('success', 200);
+    }
+
+    private function decryptBookingId(?string $encryptBookingId): ?int
+    {
+        if ($encryptBookingId === null) {
+            return null;
+        }
+
+        try {
+            return (int) Crypt::decryptString($encryptBookingId);
+        } catch (DecryptException) {
+            return null;
+        }
+    }
+}