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

app-modules/payment/src/Http/Controllers/PaymentController.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Modules\Payment\Http\Controllers;
+
+use Illuminate\Http\JsonResponse;
+use Illuminate\Routing\Controller;
+use Illuminate\Support\Facades\Gate;
+use Modules\Booking\Models\Booking;
+use Modules\Payment\Actions\InitiatePaymentAction;
+use Modules\Payment\Http\Resources\PaymentResource;
+
+class PaymentController extends Controller
+{
+    public function __construct(
+        private InitiatePaymentAction $initiatePaymentAction,
+    ) {}
+
+    public function initiate(Booking $booking): JsonResponse
+    {
+        Gate::authorize('pay', $booking);
+
+        $payment = $this->initiatePaymentAction->handle($booking);
+
+        return (new PaymentResource($payment))
+            ->response()
+            ->setStatusCode(201);
+    }
+}

app-modules/payment/src/Http/Controllers/PaymentWebhookController.php

@@ -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;
+        }
+    }
+}

app-modules/payment/src/Http/Controllers/RefundController.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Modules\Payment\Http\Controllers;
+
+use Illuminate\Http\JsonResponse;
+use Illuminate\Routing\Controller;
+use Illuminate\Support\Facades\Gate;
+use Modules\Booking\Models\Booking;
+use Modules\Payment\Actions\RefundBookingAction;
+use Modules\Payment\Http\Requests\RefundBookingRequest;
+use Modules\Payment\Http\Resources\RefundResource;
+
+class RefundController extends Controller
+{
+    public function __construct(
+        private RefundBookingAction $refundBookingAction,
+    ) {}
+
+    public function refund(RefundBookingRequest $request, Booking $booking): JsonResponse
+    {
+        Gate::authorize('refund', $booking);
+
+        $validated = $request->validated();
+
+        $refund = $this->refundBookingAction->handle(
+            $booking,
+            (string) $validated['amount'],
+            $validated['reason'],
+            $request->user()?->id,
+        );
+
+        return (new RefundResource($refund))
+            ->response()
+            ->setStatusCode(201);
+    }
+}

app-modules/payment/src/Http/Requests/RefundBookingRequest.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Modules\Payment\Http\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+/**
+ * Shape validation only — the refundable-balance check and completed-payment
+ * lookup stay in RefundBookingAction, not here.
+ */
+class RefundBookingRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, array<int, mixed>>
+     */
+    public function rules(): array
+    {
+        return [
+            'amount' => ['required', 'numeric', 'gt:0'],
+            'reason' => ['required', 'string', 'max:500'],
+        ];
+    }
+}

app-modules/payment/src/Http/Resources/PaymentResource.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Modules\Payment\Http\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+class PaymentResource extends JsonResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'booking_id' => $this->booking_id,
+            'gateway' => $this->gateway,
+            'status' => $this->status,
+            'amount' => $this->amount,
+            'currency' => $this->currency,
+            'gateway_transaction_id' => $this->gateway_transaction_id,
+            // The gateway's raw response — the client needs this to render the
+            // KBZ Mini App payment sheet (e.g. prepay_id).
+            'gateway_payload' => $this->gateway_payload,
+            'initiated_at' => $this->initiated_at,
+        ];
+    }
+}

app-modules/payment/src/Http/Resources/RefundResource.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Modules\Payment\Http\Resources;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+class RefundResource extends JsonResource
+{
+    /**
+     * Transform the resource into an array.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'payment_id' => $this->payment_id,
+            'status' => $this->status,
+            'amount' => $this->amount,
+            'reason' => $this->reason,
+            'gateway_refund_id' => $this->gateway_refund_id,
+            'requested_by' => $this->requested_by,
+            'requested_at' => $this->requested_at,
+            'completed_at' => $this->completed_at,
+        ];
+    }
+}