Feature: Moving Payment Methods to DB, adding fees, Transaction Updates, Refund Updates, General Updates to Payments

src/Payment/Drivers/BankTransferPaymentDriver.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace Modules\Core\Payment\Drivers;
+
+use Illuminate\Support\Str;
+use Lunar\DataTypes\Price;
+use Modules\Core\Payment\Contracts\Configurable;
+use Modules\Core\Payment\Contracts\SupportsPay;
+use Modules\Core\Payment\Contracts\SupportsRefunds;
+use Modules\Core\Payment\DTOs\PaymentResult;
+use Modules\Core\Payment\Enums\PaymentResultStatus;
+use Modules\Core\Payment\Events\PaymentCaptured;
+use Modules\Core\Payment\Events\PaymentRefunded;
+
+/**
+ * Manual/attested, same trust model as OfflinePaymentDriver — there is no
+ * bank API to call, so both pay() and refund() decide success immediately
+ * on a staff member's say-so (they've already sent/received the wire
+ * outside the system). Distinct from OfflinePaymentDriver in intent: this
+ * exists so a payment taken through a DIFFERENT method (e.g.
+ * cash-on-delivery) can still be REFUNDED via bank transfer — an admin
+ * chooses this driver explicitly in the refund action, independent of
+ * which driver the original payment went through (see
+ * Payment\Support\TransactionDriverAdapter::refundVia() and
+ * Order\Filament\Extensions\OrderRefundActionsExtension). pay() exists so
+ * the same driver also covers receiving a payment by bank transfer, but
+ * the admin UI for that (bank reference, notes, proof-of-transfer upload)
+ * is deliberately not built yet — see the follow-up work tracked from this
+ * session; pay() itself is complete and usable via the registry today.
+ *
+ * $reference is generated here for the same reason as OfflinePaymentDriver's
+ * pay(): there is no gateway to hand one back. 'notes' in $context (not
+ * $data — refund() has no $data parameter) is folded into
+ * PaymentResult::$meta, which Order\Services\TransactionRecorder::record()
+ * already writes straight into Transaction.meta with no extra plumbing.
+ */
+class BankTransferPaymentDriver implements Configurable, SupportsPay, SupportsRefunds
+{
+    /**
+     * Always true — no external dependency to be missing.
+     */
+    public function isConfigured(): bool
+    {
+        return true;
+    }
+
+    public function pay(string $type, Price $amount, array $data = [], array $context = []): PaymentResult
+    {
+        $result = new PaymentResult(
+            status: PaymentResultStatus::Succeeded,
+            reference: 'bank-transfer-'.Str::uuid(),
+            amount: $amount,
+            meta: array_filter(['notes' => $data['notes'] ?? null]),
+        );
+
+        PaymentCaptured::dispatch($type, $result, $context);
+
+        return $result;
+    }
+
+    public function refund(string $reference, Price $amount, array $context = []): PaymentResult
+    {
+        $result = new PaymentResult(
+            status: PaymentResultStatus::Succeeded,
+            reference: 'bank-transfer-'.Str::uuid(),
+            amount: $amount,
+            meta: array_filter(['notes' => $context['notes'] ?? null]),
+        );
+
+        PaymentRefunded::dispatch('bank-transfer', $result, $context);
+
+        return $result;
+    }
+}

src/Payment/Events/PaymentMethodCreated.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Modules\Core\Payment\Events;
+
+use Modules\Core\Payment\Models\PaymentMethod;
+
+class PaymentMethodCreated
+{
+    public function __construct(
+        public readonly PaymentMethod $method,
+    ) {}
+}

src/Payment/Events/PaymentMethodDeleted.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Modules\Core\Payment\Events;
+
+class PaymentMethodDeleted
+{
+    /**
+     * @param  array<string, mixed>  $method  Snapshot of the deleted row —
+     *   already gone from the database by dispatch time, so this can't be
+     *   a fresh PaymentMethod model instance.
+     */
+    public function __construct(
+        public readonly array $method,
+    ) {}
+}

src/Payment/Events/PaymentMethodUpdated.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Modules\Core\Payment\Events;
+
+use Modules\Core\Payment\Models\PaymentMethod;
+
+class PaymentMethodUpdated
+{
+    /**
+     * @param  array<string, mixed>  $old  Snapshot of the changed attributes
+     *   before the update.
+     */
+    public function __construct(
+        public readonly PaymentMethod $method,
+        public readonly array $old,
+    ) {}
+}

src/Payment/Events/PaymentMethodsReordered.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace Modules\Core\Payment\Events;
+
+class PaymentMethodsReordered
+{
+    /**
+     * @param  array<int, int>  $ids  PaymentMethod ids, in their new order —
+     *   the same array Filament's own reorderTable() already wrote to the
+     *   database directly (bulk SQL, not PaymentMethodService::update() —
+     *   see PaymentMethodResource's own docblock for why this is the one
+     *   PaymentMethod write that doesn't go through the service).
+     */
+    public function __construct(
+        public readonly array $ids,
+    ) {}
+}

src/Payment/Filament/Resources/PaymentMethodResource.php

@@ -3,21 +3,57 @@
 namespace Modules\Core\Payment\Filament\Resources;
 
 use Filament\Actions\Action;
+use Filament\Forms\Components\Select;
 use Filament\Forms\Components\TextInput;
 use Filament\Resources\Resource;
+use Filament\Schemas\Components\Component;
+use Filament\Schemas\Components\Utilities\Get;
+use Filament\Tables\Columns\IconColumn;
 use Filament\Tables\Columns\TextColumn;
 use Filament\Tables\Columns\ToggleColumn;
 use Filament\Tables\Table;
+use Illuminate\Support\Facades\Event;
+use Modules\Core\Payment\Events\PaymentMethodsReordered;
 use Modules\Core\Payment\Filament\Resources\PaymentMethodResource\Pages\ListPaymentMethods;
 use Modules\Core\Payment\Models\PaymentMethod;
+use Modules\Core\Payment\Services\PaymentDriverRegistry;
+use Modules\Core\Payment\Services\PaymentMethodCache;
+use Modules\Core\Payment\Services\PaymentMethodService;
 
 /**
- * One row per payment type key (config('lunar.payments.types')), seeded by
- * InstallLunarCommand — never created/deleted here, only edited. `enabled`
- * toggles inline; `data.fee` (currently the only type-specific setting, for
- * cash-on-delivery's flat surcharge — see ApplyCashOnDeliveryFee) is edited
- * via a modal action rather than a dedicated form field, since not every
- * type has the same data keys.
+ * The DB-instance layer for Payment (see docs/payments.md) — admin
+ * creatable/deletable, same as Lunar's own ShippingMethodResource. A row's
+ * `driver` is picked from a Select populated by
+ * PaymentDriverRegistry::labels() (mirrors Modules\Core\Shipping\
+ * Extensions\ShippingMethodResourceExtension::driverSelect()'s use of
+ * Shipping::getSupportedDrivers()), not a hardcoded options list, and
+ * never the raw driver class name — a third-party driver registered from
+ * its own package's service provider shows up here with no change to
+ * this class.
+ *
+ * Every write goes through Modules\Core\Payment\Services\
+ * PaymentMethodService — create/edit/delete/the enabled toggle all call
+ * it, not PaymentMethod::create()/update()/delete() directly, so cache
+ * invalidation and event dispatch happen in one place. The ONE exception
+ * is drag-to-reorder: Filament's own reorderTable() always writes the new
+ * `position` values via its own raw bulk SQL query before our
+ * afterReordering() hook ever runs — there is no seam to route that
+ * specific write through the service (short of disabling drag-reorder
+ * entirely and rebuilding it from scratch), so that hook only forgets the
+ * cache and dispatches PaymentMethodsReordered; the data itself is
+ * already correct in the database by the time it fires.
+ *
+ * `driver_missing_at` (set by the `boboko:payment:sync-drivers` command
+ * when a row's driver no longer resolves) is surfaced as its own table
+ * column, deliberately distinct from `enabled` — an admin needs to tell
+ * "I turned this off" apart from "the driver code was removed" at a
+ * glance, not have both look like the same disabled state.
+ *
+ * `authorized_status` only appears in the form when `capture_mode` is
+ * "Hold now, charge later" — it's simply unreachable for a "Charge
+ * immediately" method (that mode only ever produces PaymentCaptured,
+ * never PaymentAuthorized), so showing it unconditionally would just be
+ * a confusing, always-irrelevant field for most methods.
  */
 class PaymentMethodResource extends Resource
 {
@@ -35,10 +71,31 @@ class PaymentMethodResource extends Resource
     {
         return $table
             ->columns([
+                TextColumn::make('position')
+                    ->label('Order')
+                    ->sortable(),
+                TextColumn::make('name')
+                    ->label('Name')
+                    ->searchable(),
                 TextColumn::make('type')
                     ->label('Type'),
+                TextColumn::make('driver')
+                    ->label('Driver')
+                    ->formatStateUsing(fn (?string $state) => static::driverLabel($state)),
+                IconColumn::make('driver_missing_at')
+                    ->label('Driver status')
+                    ->boolean()
+                    ->trueIcon('heroicon-o-exclamation-triangle')
+                    ->falseIcon('heroicon-o-check-circle')
+                    ->trueColor('danger')
+                    ->falseColor('success')
+                    ->tooltip(fn (PaymentMethod $record) => $record->driver_missing_at
+                        ? 'Driver not found as of '.$record->driver_missing_at->diffForHumans()
+                        : 'Driver resolves correctly'),
                 ToggleColumn::make('enabled')
-                    ->label('Enabled'),
+                    ->label('Enabled')
+                    ->updateStateUsing(fn (PaymentMethod $record, $state) => app(PaymentMethodService::class)
+                        ->update($record, ['enabled' => $state])),
                 TextColumn::make('data.fee')
                     ->label('Fee')
                     ->formatStateUsing(fn (?int $state) => $state
@@ -48,10 +105,110 @@ class PaymentMethodResource extends Resource
                     ->label('Last updated')
                     ->dateTime(),
             ])
+            ->reorderable('position')
+            ->afterReordering(function (array $order) {
+                app(PaymentMethodCache::class)->forget();
+
+                Event::dispatch(new PaymentMethodsReordered(array_map('intval', array_values($order))));
+            })
             ->recordActions([
+                static::editAction(),
                 static::editFeeAction(),
+                static::deleteAction(),
             ])
-            ->defaultSort('type');
+            ->defaultSort('position');
+    }
+
+    /**
+     * @return array<Component>
+     */
+    public static function getFormComponents(): array
+    {
+        return [
+            TextInput::make('name')
+                ->label('Name')
+                ->required()
+                ->maxLength(255),
+            TextInput::make('type')
+                ->label('Type')
+                ->helperText('Machine-facing slug — stored on the cart/order, used by other code to identify this method. Cannot be changed once orders reference it.')
+                ->required()
+                ->unique(ignoreRecord: true)
+                ->maxLength(255),
+            static::getDriverFormComponent(),
+            Select::make('capture_mode')
+                ->label('Capture mode')
+                ->helperText('Whether checkout charges immediately, or places a hold to settle later.')
+                ->options([
+                    'pay' => 'Charge immediately',
+                    'authorize' => 'Hold now, charge later',
+                ])
+                ->default('pay')
+                ->live()
+                ->required(),
+            static::getOrderStatusSelect('captured_status', 'Order status once paid')
+                ->helperText('Applied the moment a payment is fully charged.'),
+            static::getOrderStatusSelect('authorized_status', 'Order status once held')
+                ->helperText('Applied the moment a hold is placed, before it\'s charged.')
+                ->visible(fn (Get $get) => $get('capture_mode') === 'authorize'),
+            static::getOrderStatusSelect('refunded_status', 'Order status once refunded')
+                ->helperText('Applied when a payment taken through this method is refunded — even if the refund itself is processed through a different method.'),
+        ];
+    }
+
+    public static function getDriverFormComponent(): Component
+    {
+        return Select::make('driver')
+            ->label('Driver')
+            ->options(fn () => app(PaymentDriverRegistry::class)->labels())
+            ->required();
+    }
+
+    /**
+     * Lunar's own Order::status is a plain, admin-extensible string
+     * (config('lunar.orders.statuses')) rather than a fixed enum —
+     * deliberately so a store can add its own custom status without a
+     * code change (see docs/payments.md). This Select still reads from
+     * that same open-ended list, just so an admin picks a real status
+     * instead of typing a slug from memory.
+     */
+    private static function getOrderStatusSelect(string $name, string $label): Select
+    {
+        return Select::make($name)
+            ->label($label)
+            ->options(collect(config('lunar.orders.statuses', []))
+                ->map(fn (array $status) => $status['label'] ?? $status)
+                ->all())
+            ->native(false);
+    }
+
+    public static function getPages(): array
+    {
+        return [
+            'index' => ListPaymentMethods::route('/'),
+        ];
+    }
+
+    public static function canCreate(): bool
+    {
+        return true;
+    }
+
+    public static function canDelete($record = null): bool
+    {
+        return true;
+    }
+
+    private static function editAction(): Action
+    {
+        return Action::make('edit')
+            ->label('Edit')
+            ->icon('heroicon-o-pencil-square')
+            ->schema(static::getFormComponents())
+            ->fillForm(fn (PaymentMethod $record) => $record->only([
+                'name', 'type', 'driver', 'capture_mode', 'captured_status', 'authorized_status', 'refunded_status',
+            ]))
+            ->action(fn (PaymentMethod $record, array $data) => app(PaymentMethodService::class)->update($record, $data));
     }
 
     /**
@@ -76,7 +233,7 @@ class PaymentMethodResource extends Resource
                 'fee' => filled($record->data['fee'] ?? null) ? $record->data['fee'] / 100 : null,
             ])
             ->action(function (PaymentMethod $record, array $data) {
-                $record->update([
+                app(PaymentMethodService::class)->update($record, [
                     'data' => [
                         ...$record->data->toArray(),
                         'fee' => filled($data['fee']) ? (int) round($data['fee'] * 100) : null,
@@ -85,20 +242,22 @@ class PaymentMethodResource extends Resource
             });
     }
 
-    public static function getPages(): array
+    private static function deleteAction(): Action
     {
-        return [
-            'index' => ListPaymentMethods::route('/'),
-        ];
+        return Action::make('delete')
+            ->label('Delete')
+            ->icon('heroicon-o-trash')
+            ->color('danger')
+            ->requiresConfirmation()
+            ->action(fn (PaymentMethod $record) => app(PaymentMethodService::class)->delete($record));
     }
 
-    public static function canCreate(): bool
+    private static function driverLabel(?string $key): string
     {
-        return false;
-    }
+        if ($key === null) {
+            return '—';
+        }
 
-    public static function canDelete($record = null): bool
-    {
-        return false;
+        return app(PaymentDriverRegistry::class)->label($key) ?? $key;
     }
 }

src/Payment/Filament/Resources/PaymentMethodResource/Pages/ListPaymentMethods.php

@@ -2,10 +2,31 @@
 
 namespace Modules\Core\Payment\Filament\Resources\PaymentMethodResource\Pages;
 
+use Filament\Actions;
 use Filament\Resources\Pages\ListRecords;
 use Modules\Core\Payment\Filament\Resources\PaymentMethodResource;
+use Modules\Core\Payment\Models\PaymentMethod;
+use Modules\Core\Payment\Services\PaymentMethodService;
 
 class ListPaymentMethods extends ListRecords
 {
     protected static string $resource = PaymentMethodResource::class;
+
+    protected function getHeaderActions(): array
+    {
+        return [
+            Actions\CreateAction::make()
+                ->schema(PaymentMethodResource::getFormComponents())
+                ->fillForm(fn () => [
+                    'position' => (PaymentMethod::max('position') ?? 0) + 1,
+                    'enabled' => false,
+                    'data' => [],
+                ])
+                // Every PaymentMethod write goes through PaymentMethodService
+                // — see PaymentMethodResource's own docblock — so this
+                // replaces CreateAction's default $model::create($data), not
+                // just the form/fill behavior above.
+                ->using(fn (array $data) => app(PaymentMethodService::class)->create($data)),
+        ];
+    }
 }

src/Payment/Http/Controllers/StripeWebhookController.php

@@ -23,7 +23,7 @@ use Stripe\Webhook;
  * anywhere reusable, it only gates the request through.
  *
  * Resolves the driver directly by class, not via
- * Modules\Core\Payment\Services\PaymentDriverResolver — this endpoint is
+ * Modules\Core\Payment\Services\PaymentDriverRegistry — this endpoint is
  * inherently Stripe-specific (Stripe's own webhook payload carries no
  * boboko payment-type key, only its own payment_intent id), and
  * StripePaymentDriver::handleCallback() already recovers $type itself

src/Payment/Listeners/LogPaymentMethodActivity.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace Modules\Core\Payment\Listeners;
+
+use Modules\Core\Logging\ActivityLogService;
+use Modules\Core\Payment\Events\PaymentMethodCreated;
+use Modules\Core\Payment\Events\PaymentMethodDeleted;
+use Modules\Core\Payment\Events\PaymentMethodUpdated;
+use Modules\Core\Payment\Models\PaymentMethod;
+
+/**
+ * Same pattern as Localization\Listeners\LogTranslationActivity — routes
+ * PaymentMethodService's own events through the existing
+ * Logging\ActivityLogService instead of PaymentMethod separately opting
+ * into Lunar\Base\Traits\LogsActivity (Spatie's generic model-observer
+ * logging): PaymentMethodUpdated::$old and PaymentMethodDeleted::$method
+ * already carry richer, deliberate before/after context than Eloquent's
+ * own dirty-attribute diffing would reconstruct on its own.
+ *
+ * PaymentMethodDeleted's snapshot is a plain array (the row is already
+ * gone from the database by dispatch time — see that event's own
+ * docblock), so performedOn() gets an unsaved PaymentMethod instance
+ * built from it purely to carry the right subject_type/id, not a real
+ * persisted model.
+ *
+ * PaymentMethodsReordered is deliberately NOT logged here — it's a
+ * multi-row position change (ActivityLogService's methods all take one
+ * Model $subject) for a low-stakes, purely-cosmetic setting, not worth
+ * forcing into a one-subject shape or adding a new method to the shared
+ * service for.
+ */
+class LogPaymentMethodActivity
+{
+    public function __construct(
+        private readonly ActivityLogService $activityLog,
+    ) {}
+
+    public function handleCreated(PaymentMethodCreated $event): void
+    {
+        $this->activityLog->created($event->method, $event->method->getAttributes());
+    }
+
+    public function handleUpdated(PaymentMethodUpdated $event): void
+    {
+        $this->activityLog->updated(
+            $event->method,
+            $event->old,
+            $event->method->only(array_keys($event->old)),
+        );
+    }
+
+    public function handleDeleted(PaymentMethodDeleted $event): void
+    {
+        $subject = (new PaymentMethod)->forceFill($event->method);
+        $subject->exists = true;
+        $subject->id = $event->method['id'];
+
+        $this->activityLog->deleted($subject, $event->method);
+    }
+}

src/Payment/Models/CoreTransaction.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Modules\Core\Payment\Models;
+
+use Lunar\Models\Transaction;
+use Modules\Core\Payment\Support\TransactionDriverAdapter;
+
+/**
+ * Registered via Lunar\Facades\ModelManifest::replace(Lunar\Models\
+ * Contracts\Transaction::class, self::class) in PaymentServiceProvider —
+ * the same contract-swap mechanism this codebase already uses for
+ * Customer/Staff. Every place Lunar's own code resolves a transaction via
+ * Transaction::modelClass() (which reads this replacement, see
+ * Lunar\Base\Traits\HasModelExtending::modelClass()) — including
+ * Order::transactions()'s own hasMany(Transaction::modelClass()) relation
+ * — gets an instance of THIS class instead of the vendor's own
+ * Lunar\Models\Transaction. No override anywhere else is needed: this is
+ * the one seam that makes $order->transactions, and everything the admin
+ * panel's refund/capture actions call on one of those rows, silently run
+ * through our own system.
+ *
+ * Only driver() is overridden — refund()/capture()/paymentChecks() on the
+ * parent class all just call driver()->{method}(), so replacing what
+ * driver() returns is the entire fix (see TransactionDriverAdapter).
+ */
+class CoreTransaction extends Transaction
+{
+    public function driver(): TransactionDriverAdapter
+    {
+        return app(TransactionDriverAdapter::class);
+    }
+}

src/Payment/Models/PaymentMethod.php

@@ -6,17 +6,35 @@ use Illuminate\Database\Eloquent\Casts\AsArrayObject;
 use Illuminate\Database\Eloquent\Model;
 
 /**
- * Admin-editable settings for one payment type key (matching a key in
- * config('lunar.payments.types')) — enabled/disabled, and whatever type-
- * specific data it needs (starts with 'fee' for cash-on-delivery's flat
- * surcharge). Mirrors Lunar's own Discount model: a single jsonb 'data'
- * column holding keyed settings, rather than a fixed column per setting or
- * a separate conditions table — new settings are a code change (a new key
- * read from data), not a migration.
- *
- * Seeded once per type by InstallLunarCommand (skip-if-exists, same
- * idempotent convention as seedStorefrontLabels()) — never auto-created on
- * read, so a read path stays a pure read.
+ * A merchant-configured payment method — the DB-instance layer, admin
+ * creatable/deletable, same split Modules\Core\Shipping's own
+ * shipping_methods table already has (see docs/payments.md):
+ *   - type: unique, machine-facing slug (Cart::meta['payment_method'],
+ *     ApplyCashOnDeliveryFee's lookup key, every Payment event's $type).
+ *   - name: admin-facing label.
+ *   - driver: the Modules\Core\Payment\Services\PaymentDriverRegistry key
+ *     — NOT the same as `type`, and not unique (two rows can share one
+ *     driver, e.g. two differently-named offline-style methods).
+ *   - capture_mode: 'pay' or 'authorize' — which SupportsPay/
+ *     SupportsAuthorization method CheckoutService::initiatePayment()
+ *     calls for this row.
+ *   - captured_status / authorized_status / refunded_status: the
+ *     Order::status value Modules\Core\Order\Listeners\
+ *     ApplyResolvedPaymentStatus applies on a PaymentCaptured/
+ *     PaymentAuthorized/PaymentRefunded event. For a refund, this is
+ *     always the ORIGINAL payment method's row (the one the customer
+ *     actually paid with), never the driver the refund itself was routed
+ *     through (Payment\Support\TransactionDriverAdapter::refundVia() may
+ *     use a different one entirely — e.g. a cash-on-delivery order
+ *     refunded via a Bank Transfer driver with no PaymentMethod row of
+ *     its own) — see that listener's own docblock.
+ *   - position: admin-controlled display/checkout order.
+ *   - driver_missing_at: set by `payment:sync-drivers` when `driver` no
+ *     longer resolves via the registry — separate from `enabled`, so a
+ *     driver vanishing (a deploy removed it) is never confused with an
+ *     admin's own manual toggle.
+ *   - data: jsonb, driver-specific settings that don't warrant their own
+ *     column (starts with 'fee', the offline flat surcharge).
  */
 class PaymentMethod extends Model
 {
@@ -24,6 +42,8 @@ class PaymentMethod extends Model
 
     protected $casts = [
         'enabled' => 'boolean',
+        'position' => 'integer',
+        'driver_missing_at' => 'datetime',
         'data' => AsArrayObject::class,
     ];
 }

src/Payment/Services/PaymentDriverRegistry.php

@@ -0,0 +1,107 @@
+<?php
+
+namespace Modules\Core\Payment\Services;
+
+/**
+ * Which payment driver CLASSES exist this deploy — the code-registry layer,
+ * mirroring Lunar\Shipping\Managers\ShippingManager's own built-in-methods
+ * + Manager::extend() pattern, but purpose-built rather than extending
+ * Illuminate\Support\Manager: Manager's create{X}Driver() convention fits
+ * a uniform one-interface-per-driver contract (ShippingRateInterface); a
+ * Payment driver instead implements several independent, opt-in capability
+ * interfaces at once (Configurable, SupportsPay, SupportsAuthorization,
+ * ...), so there's no single "the" method to generate per driver.
+ *
+ * Deliberately knows NOTHING about Modules\Core\Payment\Models\PaymentMethod
+ * or the database — resolve() is a pure "does this key still exist"
+ * lookup. Whether a resolved driver is administratively enabled, or
+ * reports itself Configurable::isConfigured(), is the DOMAIN's job
+ * (Modules\Core\Checkout\Services\CheckoutService::getPaymentMethods()) —
+ * see docs/payments.md. This split is what lets the identical registry
+ * shape be lifted for a future Invoicing/AntiFraud domain without dragging
+ * Payment-specific concepts along with it.
+ *
+ * Built-in drivers are registered in Modules\Core\Providers\
+ * PaymentServiceProvider::boot() via register(); a consuming app or a
+ * future payment-provider package registers its own the same way, from
+ * its own service provider's boot() — exactly how Shipping::extend() works
+ * for ACS/Box Now (src/Providers/ShippingServiceProvider.php).
+ */
+class PaymentDriverRegistry
+{
+    /**
+     * @var array<string, string>
+     */
+    private array $drivers = [];
+
+    /**
+     * @var array<string, string>
+     */
+    private array $labels = [];
+
+    /**
+     * $key is the registry key a Modules\Core\Payment\Models\PaymentMethod
+     * row's own `driver` column stores — NOT the same as that row's `type`
+     * (its merchant-facing slug). Two rows can share one driver key (e.g.
+     * both 'cash-on-delivery' and 'cash-in-hand' using the same 'offline'
+     * driver with different type/name/fee).
+     *
+     * $label is a short, human-readable name (e.g. "Stripe", "Offline /
+     * Manual") — this is where that comes from, not $driverClass's own
+     * FQCN. Payment's driver classes implement several independent,
+     * opt-in capability interfaces (Configurable, SupportsPay, ...), none
+     * of which carries a display name the way Lunar\Shipping\Interfaces\
+     * ShippingRateInterface::name() does for every shipping driver — the
+     * registry is the one place that DOES know every driver at once, so
+     * it's the natural (and only) place to also hold this.
+     */
+    public function register(string $key, string $driverClass, string $label): void
+    {
+        $this->drivers[$key] = $driverClass;
+        $this->labels[$key] = $label;
+    }
+
+    /**
+     * Null if $key was never registered — deliberately non-throwing, same
+     * reasoning the old PaymentDriverResolver already had: a caller
+     * checking availability (or the payment:sync-drivers command checking
+     * every PaymentMethod row) needs "not found" to be a normal, silent
+     * result, not an exception to catch.
+     */
+    public function resolve(string $key): ?object
+    {
+        $driverClass = $this->drivers[$key] ?? null;
+
+        return $driverClass ? app($driverClass) : null;
+    }
+
+    /**
+     * Every registered key => driver class — what payment:sync-drivers
+     * checks every PaymentMethod row's `driver` column against.
+     *
+     * @return array<string, string>
+     */
+    public function all(): array
+    {
+        return $this->drivers;
+    }
+
+    /**
+     * Every registered key => human-readable label — what a Filament
+     * driver Select populates its options from (mirroring
+     * ShippingMethodResourceExtension::driverSelect()'s use of
+     * Shipping::getSupportedDrivers(), which reads each driver's own
+     * name()) — never the raw class name from all().
+     *
+     * @return array<string, string>
+     */
+    public function labels(): array
+    {
+        return $this->labels;
+    }
+
+    public function label(string $key): ?string
+    {
+        return $this->labels[$key] ?? null;
+    }
+}

src/Payment/Services/PaymentDriverResolver.php

@@ -1,34 +0,0 @@
-<?php
-
-namespace Modules\Core\Payment\Services;
-
-/**
- * Resolves a payment type key (e.g. 'stripe', 'cash-on-delivery') to its
- * registered driver instance — extracted out of CheckoutService so both it
- * and anything else needing the same lookup share one implementation
- * instead of duplicating this config read.
- *
- * Returns a plain object, not a shared interface — Payment's own drivers
- * implement several independent, orthogonal capability interfaces at once
- * (Configurable, SupportsPay, SupportsAuthorization, ...; see
- * StripePaymentDriver implementing all six). There is no single common
- * "PaymentDriver" contract to type this against; a caller checks
- * `instanceof SupportsPay` / `instanceof SupportsAuthorization` itself,
- * the same way Payment's own contracts are designed to be consumed.
- */
-class PaymentDriverResolver
-{
-    /**
-     * Null if $type has no 'payment_driver' registered in
-     * config('lunar.payments.types.<type>') at all — deliberately
-     * non-throwing so a caller like CheckoutService::getPaymentMethods()
-     * can filter unresolvable types silently rather than treating "not
-     * registered" as an error condition when just checking availability.
-     */
-    public function resolve(string $type): ?object
-    {
-        $driverClass = config("lunar.payments.types.{$type}.payment_driver");
-
-        return $driverClass ? app($driverClass) : null;
-    }
-}

src/Payment/Services/PaymentMethodCache.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace Modules\Core\Payment\Services;
+
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Cache;
+use Modules\Core\Payment\Models\PaymentMethod;
+
+/**
+ * Cached read layer over PaymentMethod — the single source both
+ * Modules\Core\Checkout\Services\CheckoutService (checkout-time
+ * availability) and anything else needing the payment-method list (e.g.
+ * PaymentServiceProvider's Lunar\Facades\Payments shim, order screens
+ * showing a transaction's driver) read from, so the table is fetched once
+ * per cache lifetime rather than once per caller/request. Mirrors
+ * Modules\Core\Localization\Services\LanguageCache's exact shape.
+ *
+ * Cached forever, invalidated via forget() by
+ * Modules\Core\Payment\Observers\FlushPaymentMethodCache on
+ * PaymentMethod::saved()/deleted() — no bespoke Created/Updated/Deleted
+ * event trio needed, unlike LanguageCache's (Language is a Lunar-owned
+ * model reacted to indirectly); PaymentMethod is entirely our own model,
+ * so a plain Eloquent observer is the direct route.
+ */
+class PaymentMethodCache
+{
+    private const CACHE_KEY = 'core.payment.methods';
+
+    public function all(): Collection
+    {
+        return Cache::rememberForever(
+            self::CACHE_KEY,
+            fn () => PaymentMethod::query()->orderBy('position')->get(),
+        );
+    }
+
+    public function forget(): void
+    {
+        Cache::forget(self::CACHE_KEY);
+    }
+}

src/Payment/Services/PaymentMethodService.php

@@ -0,0 +1,83 @@
+<?php
+
+namespace Modules\Core\Payment\Services;
+
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Event;
+use Modules\Core\Payment\Events\PaymentMethodCreated;
+use Modules\Core\Payment\Events\PaymentMethodDeleted;
+use Modules\Core\Payment\Events\PaymentMethodUpdated;
+use Modules\Core\Payment\Models\PaymentMethod;
+
+/**
+ * The single write (AND read) gateway for PaymentMethod — every Filament
+ * resource/action calls this, not PaymentMethod::create()/update()/delete()
+ * directly, so cache invalidation is one explicit step colocated with the
+ * mutation (not hidden in a model observer) and every admin change to a
+ * payment method dispatches a matching event, the same convention
+ * Modules\Core\Cart\Services\CartService already established for its own
+ * mutating methods.
+ *
+ * list() is what PaymentMethodCache actually reads through — see that
+ * class for why this needs caching at all (Modules\Core\Checkout\
+ * Services\CheckoutService and PaymentServiceProvider's Lunar\Facades\
+ * Payments shim both read the full payment-method list on the hot path).
+ */
+class PaymentMethodService
+{
+    public function __construct(
+        private readonly PaymentMethodCache $cache,
+    ) {}
+
+    /**
+     * @return Collection<int, PaymentMethod>
+     */
+    public function list(): Collection
+    {
+        return $this->cache->all();
+    }
+
+    /**
+     * @param  array<string, mixed>  $data
+     */
+    public function create(array $data): PaymentMethod
+    {
+        $method = PaymentMethod::create($data);
+
+        $this->cache->forget();
+
+        Event::dispatch(new PaymentMethodCreated($method));
+
+        return $method;
+    }
+
+    /**
+     * @param  array<string, mixed>  $data
+     */
+    public function update(PaymentMethod $method, array $data): PaymentMethod
+    {
+        $old = $method->only(array_keys($data));
+
+        $method->update($data);
+
+        $this->cache->forget();
+
+        Event::dispatch(new PaymentMethodUpdated($method, $old));
+
+        return $method;
+    }
+
+    public function delete(PaymentMethod $method): void
+    {
+        $snapshot = $method->only([
+            'id', 'type', 'name', 'driver', 'capture_mode',
+            'captured_status', 'authorized_status', 'position', 'enabled',
+        ]);
+
+        $method->delete();
+
+        $this->cache->forget();
+
+        Event::dispatch(new PaymentMethodDeleted($snapshot));
+    }
+}

src/Payment/Support/TransactionDriverAdapter.php

@@ -0,0 +1,144 @@
+<?php
+
+namespace Modules\Core\Payment\Support;
+
+use Lunar\Base\DataTransferObjects\PaymentCapture;
+use Lunar\Base\DataTransferObjects\PaymentChecks;
+use Lunar\Base\DataTransferObjects\PaymentRefund;
+use Lunar\DataTypes\Price;
+use Lunar\Models\Contracts\Transaction;
+use Modules\Core\Payment\Contracts\SupportsCaptures;
+use Modules\Core\Payment\Contracts\SupportsRefunds;
+use Modules\Core\Payment\Enums\PaymentResultStatus;
+use Modules\Core\Payment\Services\PaymentDriverRegistry;
+use Modules\Core\Payment\Services\PaymentMethodCache;
+
+/**
+ * What Modules\Core\Payment\Models\CoreTransaction::driver() returns
+ * instead of Lunar\Facades\Payments::driver($this->driver) — the point
+ * where every Lunar-native caller of a transaction's driver (today: the
+ * admin panel's "Refund"/"Capture" header actions on the order page,
+ * ManageOrder::getRefundAction()/getCaptureAction() — see
+ * $transaction->refund()/->capture() in vendor/lunarphp/core/src/Models/
+ * Transaction.php) transparently lands on OUR real payment system instead
+ * of Lunar's own, entirely separate, unused PaymentManager.
+ *
+ * Implements Lunar\Base\PaymentTypeInterface's refund()/capture()/
+ * getPaymentChecks() signatures exactly — each takes the Transaction as
+ * its own first argument (confirmed from vendor/lunarphp/core/src/Models/
+ * Transaction.php: `$this->driver()->refund($this, $amount, $notes)`),
+ * so this class holds no transaction state of its own; CoreTransaction's
+ * driver() can return one shared instance for any transaction.
+ *
+ * $transaction->driver is a Modules\Core\Payment\Models\PaymentMethod.type
+ * value (what Modules\Core\Order\Services\TransactionRecorder writes into
+ * Transaction.driver) — this resolves the REAL registry key from that
+ * type via PaymentMethodCache, then the real driver instance from
+ * PaymentDriverRegistry, so refund()/capture() called here call the
+ * ACTUAL Stripe/etc. driver, never a fake/no-op stand-in. If either
+ * lookup fails (the PaymentMethod row or its driver no longer exists),
+ * refund()/capture() report failure rather than silently doing nothing.
+ */
+class TransactionDriverAdapter
+{
+    public function __construct(
+        private readonly PaymentMethodCache $paymentMethods,
+        private readonly PaymentDriverRegistry $registry,
+    ) {}
+
+    public function refund(Transaction $transaction, int $amount, ?string $notes = null): PaymentRefund
+    {
+        return $this->refundVia($transaction, $this->driverKeyFor($transaction), $amount, $notes);
+    }
+
+    /**
+     * The PaymentDriverRegistry key $transaction was originally taken
+     * through — what refund()/capture() resolve against by default, and
+     * what Order\Filament\Extensions\OrderRefundActionsExtension defaults
+     * its "Refund via" driver Select to, before an admin overrides it.
+     */
+    public function driverKeyFor(Transaction $transaction): ?string
+    {
+        return $this->paymentMethods->all()->firstWhere('type', $transaction->driver)?->driver;
+    }
+
+    /**
+     * Same as refund(), but against an explicitly chosen driver rather than
+     * the one $transaction was originally taken through — e.g. refunding a
+     * cash-on-delivery order via a Bank Transfer driver instead of trying
+     * (and failing) to refund through the offline driver that took the
+     * original payment. $driverKey is a PaymentDriverRegistry key (e.g.
+     * 'bank-transfer'), not a PaymentMethod.type — the two only coincide
+     * when refunding through the transaction's own original driver.
+     *
+     * Called directly by Order\Filament\Extensions\
+     * OrderRefundActionsExtension when the admin picks a different driver
+     * in the refund modal, bypassing Lunar\Models\Transaction::refund()
+     * (whose fixed refund(int $amount, $notes = null) signature has no
+     * room for a driver override) — see that extension's own docblock.
+     */
+    public function refundVia(Transaction $transaction, ?string $driverKey, int $amount, ?string $notes = null): PaymentRefund
+    {
+        $driver = $driverKey !== null ? $this->registry->resolve($driverKey) : null;
+
+        if (! $driver instanceof SupportsRefunds) {
+            return new PaymentRefund(success: false, message: 'This payment method does not support refunds.');
+        }
+
+        $result = $driver->refund(
+            $transaction->reference,
+            $this->priceFor($transaction, $amount),
+            ['notes' => $notes, 'order_id' => $transaction->order_id],
+        );
+
+        return new PaymentRefund(
+            success: $result->status === PaymentResultStatus::Succeeded,
+            message: $result->failureReason,
+        );
+    }
+
+    public function capture(Transaction $transaction, int $amount = 0): PaymentCapture
+    {
+        $driver = $this->resolveDriver($transaction);
+
+        if (! $driver instanceof SupportsCaptures) {
+            return new PaymentCapture(success: false, message: 'This payment method does not support a separate capture step.');
+        }
+
+        $result = $driver->capture(
+            $transaction->reference,
+            $this->priceFor($transaction, $amount ?: $transaction->amount->value),
+            ['order_id' => $transaction->order_id],
+        );
+
+        return new PaymentCapture(
+            success: $result->status === PaymentResultStatus::Succeeded,
+            message: $result->failureReason ?? '',
+        );
+    }
+
+    /**
+     * Lunar's own PaymentChecks DTO (address/postcode/CVC verification
+     * results) has no equivalent in our own contracts — none of our
+     * drivers currently surface this level of gateway-specific detail.
+     * Empty, not null: Lunar's admin panel iterates this collection to
+     * render a checks list, so it needs to always be a valid (possibly
+     * empty) PaymentChecks, never missing entirely.
+     */
+    public function getPaymentChecks(Transaction $transaction): PaymentChecks
+    {
+        return new PaymentChecks;
+    }
+
+    private function resolveDriver(Transaction $transaction): ?object
+    {
+        $driverKey = $this->driverKeyFor($transaction);
+
+        return $driverKey !== null ? $this->registry->resolve($driverKey) : null;
+    }
+
+    private function priceFor(Transaction $transaction, int $amount): Price
+    {
+        return new Price($amount, $transaction->order->currency);
+    }
+}