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/booking/src/Actions/CancelBookingAction.php

@@ -5,17 +5,37 @@ namespace Modules\Booking\Actions;
 use Modules\Booking\Enums\BookingStatus;
 use Modules\Booking\Exceptions\BookingCannotBeCancelledException;
 use Modules\Booking\Models\Booking;
+use Modules\Payment\Actions\RefundBookingAction;
 
 /**
- * Unpaid path only — a pending_payment booking has no money moved yet, so
- * it can be cancelled directly. A confirmed (paid) booking must go through
- * a refund first; this action explicitly guards against bypassing that
- * (domain.md §5). Wired into that refund path in T5.12.
+ * A pending_payment booking has no money moved yet, so it cancels directly.
+ * A confirmed (paid) booking is cancelled by refunding it in full first —
+ * delegates to RefundBookingAction (Payment module); the booking only
+ * actually flips to cancelled once that refund succeeds, via
+ * RefundProcessed/MarkBookingRefunded, not here (domain.md §5). Any other
+ * status (already cancelled/expired) is rejected outright.
  */
 class CancelBookingAction
 {
-    public function handle(Booking $booking): Booking
+    private const CANCELLATION_REFUND_REASON = 'Booking cancellation';
+
+    public function __construct(
+        private RefundBookingAction $refundBookingAction,
+    ) {}
+
+    public function handle(Booking $booking, ?int $requestedBy = null): Booking
     {
+        if ($booking->status === BookingStatus::Confirmed) {
+            $this->refundBookingAction->handle(
+                $booking,
+                (string) $booking->price,
+                self::CANCELLATION_REFUND_REASON,
+                $requestedBy,
+            );
+
+            return $booking->refresh();
+        }
+
         if ($booking->status !== BookingStatus::PendingPayment) {
             throw BookingCannotBeCancelledException::notPendingPayment($booking);
         }

app-modules/booking/src/Exceptions/BookingCannotBeCancelledException.php

@@ -4,19 +4,20 @@ namespace Modules\Booking\Exceptions;
 
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
-use Modules\Booking\Enums\BookingStatus;
 use Modules\Booking\Models\Booking;
 use RuntimeException;
 
 class BookingCannotBeCancelledException extends RuntimeException
 {
+    /**
+     * Confirmed bookings no longer reach this — CancelBookingAction (T5.12)
+     * refunds them instead. This is only for statuses that can't be
+     * cancelled at all (already cancelled/expired).
+     */
     public static function notPendingPayment(Booking $booking): self
     {
         return new self(
-            "Booking [{$booking->booking_ref}] cannot be cancelled directly because its status is [{$booking->status->value}]."
-            .($booking->status === BookingStatus::Confirmed
-                ? ' A confirmed (paid) booking must go through a refund first.'
-                : '')
+            "Booking [{$booking->booking_ref}] cannot be cancelled because its status is [{$booking->status->value}]."
         );
     }
 

app-modules/booking/src/Filament/Resources/Bookings/Schemas/BookingInfolist.php

@@ -8,6 +8,7 @@ use Filament\Schemas\Components\Grid;
 use Filament\Schemas\Components\Section;
 use Filament\Schemas\Schema;
 use Modules\Booking\Enums\BookingStatus;
+use Modules\Payment\Enums\PaymentStatus;
 
 class BookingInfolist
 {
@@ -92,6 +93,34 @@ class BookingInfolist
                                 TextEntry::make('car_model')->label('Car Model')->placeholder('—'),
                             ]),
                     ]),
+                // A booking can have more than one payment attempt if an
+                // earlier one failed and the customer retried (domain.md §1)
+                // — full detail (gateway response, refunds) lives on the
+                // Payment/Refund Filament resources (T5.13), this is just a
+                // quick-glance summary from the booking side.
+                Section::make('Payments')
+                    ->schema([
+                        RepeatableEntry::make('payments')
+                            ->label('')
+                            ->schema([
+                                Grid::make(6)
+                                    ->schema([
+                                        TextEntry::make('gateway')->badge(),
+                                        TextEntry::make('status')
+                                            ->badge()
+                                            ->color(fn (PaymentStatus $state) => match ($state) {
+                                                PaymentStatus::Pending => 'warning',
+                                                PaymentStatus::Completed => 'success',
+                                                PaymentStatus::Failed => 'danger',
+                                            }),
+                                        TextEntry::make('amount')->numeric(2),
+                                        TextEntry::make('currency'),
+                                        TextEntry::make('gateway_transaction_id')->label('Gateway Txn ID')->placeholder('—'),
+                                        TextEntry::make('completed_at')->dateTime()->placeholder('—'),
+                                    ]),
+                            ])
+                            ->placeholder('No payment attempts yet.'),
+                    ]),
             ]);
     }
 }

app-modules/booking/src/Http/Controllers/BookingController.php

@@ -88,11 +88,11 @@ class BookingController extends Controller
             ->setStatusCode(201);
     }
 
-    public function cancel(Booking $booking): BookingResource
+    public function cancel(Request $request, Booking $booking): BookingResource
     {
         Gate::authorize('cancel', $booking);
 
-        $this->cancelBookingAction->handle($booking);
+        $this->cancelBookingAction->handle($booking, $request->user()?->id);
 
         return new BookingResource($booking->load(self::EAGER_LOADS));
     }

app-modules/booking/src/Policies/BookingPolicy.php

@@ -3,6 +3,7 @@
 namespace Modules\Booking\Policies;
 
 use App\Models\User;
+use Modules\Booking\Enums\BookingStatus;
 use Modules\Booking\Models\Booking;
 
 class BookingPolicy
@@ -33,12 +34,18 @@ class BookingPolicy
     }
 
     /**
-     * A booking's owner may cancel their own (still pending_payment only —
-     * enforced by CancelBookingAction, not here); staff can cancel any
-     * booking via manage_bookings (domain.md §8).
+     * A booking's owner may cancel their own pending_payment booking; staff
+     * can cancel any pending_payment booking via manage_bookings. Cancelling
+     * a confirmed (paid) booking refunds it (CancelBookingAction, T5.12) —
+     * that's the same authorization boundary as refund(), staff only
+     * (domain.md §8: refund initiation is a staff-only operation).
      */
     public function cancel(User $user, Booking $booking): bool
     {
+        if ($booking->status === BookingStatus::Confirmed) {
+            return $user->can('process_refunds');
+        }
+
         return $user->id === $booking->user_id || $user->can('manage_bookings');
     }
 
@@ -46,4 +53,14 @@ class BookingPolicy
     {
         return $user->can('process_refunds');
     }
+
+    /**
+     * A booking's owner may pay for their own (still pending_payment only —
+     * enforced by InitiatePaymentAction, not here); staff can initiate on
+     * behalf of a customer via manage_bookings.
+     */
+    public function pay(User $user, Booking $booking): bool
+    {
+        return $user->id === $booking->user_id || $user->can('manage_bookings');
+    }
 }

app-modules/booking/tests/Feature/BookingCancelApiTest.php

@@ -3,10 +3,48 @@
 use App\Models\User;
 use Modules\Booking\Enums\BookingStatus;
 use Modules\Booking\Models\Booking;
+use Modules\Payment\Contracts\PaymentGatewayInterface;
+use Modules\Payment\Data\PaymentRequestData;
+use Modules\Payment\Data\PaymentResultData;
+use Modules\Payment\Data\RefundResultData;
+use Modules\Payment\Enums\PaymentMethod;
+use Modules\Payment\Enums\RefundStatus;
+use Modules\Payment\Factories\PaymentGatewayFactory;
+use Modules\Payment\Models\Payment;
 use Spatie\Permission\Models\Permission;
 
+/**
+ * Never calls the real KBZ refund API in tests.
+ */
+class FakeCancelApiRefundGateway implements PaymentGatewayInterface
+{
+    public function initiate(PaymentRequestData $data): PaymentResultData
+    {
+        throw new RuntimeException('not needed for this test');
+    }
+
+    public function verify(string $gatewayTransactionId): PaymentResultData
+    {
+        throw new RuntimeException('not needed for this test');
+    }
+
+    public function refund(string $gatewayTransactionId, string $amount, string $reason): RefundResultData
+    {
+        return new RefundResultData(status: RefundStatus::Completed, gatewayRefundId: 'REFUND123', gatewayPayload: []);
+    }
+
+    public function handleWebhook(array $payload): PaymentResultData
+    {
+        throw new RuntimeException('not needed for this test');
+    }
+}
+
 beforeEach(function () {
-    Permission::findOrCreate('manage_bookings', 'web');
+    foreach (['manage_bookings', 'process_refunds'] as $permission) {
+        Permission::findOrCreate($permission, 'web');
+    }
+
+    app(PaymentGatewayFactory::class)->register(PaymentMethod::KbzMiniApp, FakeCancelApiRefundGateway::class);
 
     $this->owner = User::factory()->create();
     $this->token = $this->owner->createToken('test-token')->plainTextToken;
@@ -23,10 +61,43 @@ test('the owner can cancel their own pending_payment booking', function () {
     expect($booking->refresh()->status)->toBe(BookingStatus::Cancelled);
 });
 
-test('cancelling a confirmed booking surfaces as 422 and leaves it untouched', function () {
+test('the owner cannot cancel their own confirmed booking without process_refunds', function () {
     $booking = Booking::factory()->create(['user_id' => $this->owner->id, 'status' => BookingStatus::Confirmed]);
 
     $this->withHeader('Authorization', "Bearer {$this->token}")
+        ->postJson("/api/v1/bookings/{$booking->booking_ref}/cancel")
+        ->assertForbidden();
+
+    expect($booking->refresh()->status)->toBe(BookingStatus::Confirmed);
+});
+
+test('staff with process_refunds can cancel a confirmed booking, which refunds it in full', function () {
+    $staff = User::factory()->create()->givePermissionTo('process_refunds');
+    $staffToken = $staff->createToken('staff-token')->plainTextToken;
+
+    $booking = Booking::factory()->create(['user_id' => $this->owner->id, 'status' => BookingStatus::Confirmed, 'price' => 15000]);
+    Payment::factory()->completed()->create([
+        'booking_id' => $booking->id,
+        'gateway' => PaymentMethod::KbzMiniApp,
+        'amount' => 15000,
+        'gateway_transaction_id' => 'EVB-CANCEL-API-1',
+    ]);
+
+    $this->withHeader('Authorization', "Bearer {$staffToken}")
+        ->postJson("/api/v1/bookings/{$booking->booking_ref}/cancel")
+        ->assertSuccessful()
+        ->assertJsonPath('data.status', BookingStatus::Cancelled->value);
+
+    expect($booking->refresh()->status)->toBe(BookingStatus::Cancelled);
+});
+
+test('cancelling a confirmed booking with no completed payment surfaces as 422 and leaves it untouched', function () {
+    $staff = User::factory()->create()->givePermissionTo('process_refunds');
+    $staffToken = $staff->createToken('staff-token')->plainTextToken;
+
+    $booking = Booking::factory()->create(['user_id' => $this->owner->id, 'status' => BookingStatus::Confirmed]);
+
+    $this->withHeader('Authorization', "Bearer {$staffToken}")
         ->postJson("/api/v1/bookings/{$booking->booking_ref}/cancel")
         ->assertStatus(422);
 

app-modules/booking/tests/Feature/BookingResourceTest.php

@@ -7,15 +7,18 @@ use Modules\Booking\Filament\Resources\Bookings\Pages\ListBookings;
 use Modules\Booking\Filament\Resources\Bookings\Pages\ViewBooking;
 use Modules\Booking\Models\Booking;
 use Modules\Booking\Models\BookingVehicleOption;
+use Modules\Payment\Enums\PaymentMethod;
+use Modules\Payment\Enums\PaymentStatus;
+use Modules\Payment\Models\Payment;
 use Modules\Shared\Enums\VehicleOption;
 use Spatie\Permission\Models\Permission;
 
 beforeEach(function () {
-    foreach (['view_bookings', 'manage_bookings'] as $permission) {
+    foreach (['view_bookings', 'manage_bookings', 'process_refunds'] as $permission) {
         Permission::findOrCreate($permission, 'web');
     }
 
-    $this->admin = User::factory()->create()->givePermissionTo(['view_bookings', 'manage_bookings']);
+    $this->admin = User::factory()->create()->givePermissionTo(['view_bookings', 'manage_bookings', 'process_refunds']);
     $this->actingAs($this->admin);
 });
 
@@ -114,6 +117,29 @@ test('can view a booking\'s detail page', function () {
         ->assertSee($booking->dropoff_address);
 });
 
+test('the booking detail page shows its related payments', function () {
+    $booking = Booking::factory()->create();
+
+    Payment::factory()->completed()->create([
+        'booking_id' => $booking->id,
+        'gateway' => PaymentMethod::KbzMiniApp,
+        'gateway_transaction_id' => 'EVB-INFOLIST-TEST-1',
+    ]);
+
+    Livewire::test(ViewBooking::class, ['record' => $booking->getRouteKey()])
+        ->assertOk()
+        ->assertSee('EVB-INFOLIST-TEST-1')
+        ->assertSee(PaymentStatus::Completed->value);
+});
+
+test('the booking detail page shows a placeholder when there are no payments yet', function () {
+    $booking = Booking::factory()->create();
+
+    Livewire::test(ViewBooking::class, ['record' => $booking->getRouteKey()])
+        ->assertOk()
+        ->assertSee('No payment attempts yet.');
+});
+
 test('the assign driver action is visible for a confirmed booking and hidden otherwise', function () {
     $confirmed = Booking::factory()->create(['status' => BookingStatus::Confirmed]);
     $pending = Booking::factory()->create(['status' => BookingStatus::PendingPayment]);

app-modules/booking/tests/Unit/CancelBookingActionTest.php

@@ -4,35 +4,84 @@ use Modules\Booking\Actions\CancelBookingAction;
 use Modules\Booking\Enums\BookingStatus;
 use Modules\Booking\Exceptions\BookingCannotBeCancelledException;
 use Modules\Booking\Models\Booking;
+use Modules\Payment\Contracts\PaymentGatewayInterface;
+use Modules\Payment\Data\PaymentRequestData;
+use Modules\Payment\Data\PaymentResultData;
+use Modules\Payment\Data\RefundResultData;
+use Modules\Payment\Enums\PaymentMethod;
+use Modules\Payment\Enums\RefundStatus;
+use Modules\Payment\Factories\PaymentGatewayFactory;
+use Modules\Payment\Models\Payment;
 
-test('it cancels a pending_payment booking', function () {
+/**
+ * Never calls the real KBZ refund API in tests.
+ */
+class FakeCancelRefundGateway implements PaymentGatewayInterface
+{
+    public static ?string $lastAmount = null;
+
+    public function initiate(PaymentRequestData $data): PaymentResultData
+    {
+        throw new RuntimeException('not needed for this test');
+    }
+
+    public function verify(string $gatewayTransactionId): PaymentResultData
+    {
+        throw new RuntimeException('not needed for this test');
+    }
+
+    public function refund(string $gatewayTransactionId, string $amount, string $reason): RefundResultData
+    {
+        self::$lastAmount = $amount;
+
+        return new RefundResultData(status: RefundStatus::Completed, gatewayRefundId: 'REFUND123', gatewayPayload: []);
+    }
+
+    public function handleWebhook(array $payload): PaymentResultData
+    {
+        throw new RuntimeException('not needed for this test');
+    }
+}
+
+beforeEach(function () {
+    FakeCancelRefundGateway::$lastAmount = null;
+    app(PaymentGatewayFactory::class)->register(PaymentMethod::KbzMiniApp, FakeCancelRefundGateway::class);
+});
+
+test('it cancels a pending_payment booking directly', function () {
     $booking = Booking::factory()->create(['status' => BookingStatus::PendingPayment]);
 
-    $cancelled = (new CancelBookingAction)->handle($booking);
+    $cancelled = app(CancelBookingAction::class)->handle($booking);
 
     expect($cancelled->status)->toBe(BookingStatus::Cancelled)
         ->and($booking->refresh()->status)->toBe(BookingStatus::Cancelled);
 });
 
-test('it guards against cancelling a confirmed booking', function () {
-    $booking = Booking::factory()->create(['status' => BookingStatus::Confirmed]);
+test('it cancels a confirmed booking by refunding it in full', function () {
+    $booking = Booking::factory()->create(['status' => BookingStatus::Confirmed, 'price' => 15000]);
+    Payment::factory()->completed()->create([
+        'booking_id' => $booking->id,
+        'gateway' => PaymentMethod::KbzMiniApp,
+        'amount' => 15000,
+        'gateway_transaction_id' => 'EVB-CANCEL-TEST-1',
+    ]);
 
-    expect(fn () => (new CancelBookingAction)->handle($booking))
-        ->toThrow(BookingCannotBeCancelledException::class);
+    $cancelled = app(CancelBookingAction::class)->handle($booking);
 
-    expect($booking->refresh()->status)->toBe(BookingStatus::Confirmed);
+    expect($cancelled->status)->toBe(BookingStatus::Cancelled)
+        ->and(FakeCancelRefundGateway::$lastAmount)->toBe('15000.00');
 });
 
 test('it guards against cancelling an already cancelled booking', function () {
     $booking = Booking::factory()->create(['status' => BookingStatus::Cancelled]);
 
-    expect(fn () => (new CancelBookingAction)->handle($booking))
+    expect(fn () => app(CancelBookingAction::class)->handle($booking))
         ->toThrow(BookingCannotBeCancelledException::class);
 });
 
 test('it guards against cancelling an expired booking', function () {
     $booking = Booking::factory()->create(['status' => BookingStatus::Expired]);
 
-    expect(fn () => (new CancelBookingAction)->handle($booking))
+    expect(fn () => app(CancelBookingAction::class)->handle($booking))
         ->toThrow(BookingCannotBeCancelledException::class);
 });