Feature: Payment resolver, Payment Provider, Completing Stripe Webhooks, Wiring Payments to checkout service

src/Payment/Services/PaymentDriverResolver.php

@@ -2,14 +2,19 @@
 
 namespace Modules\Core\Payment\Services;
 
-use Modules\Core\Payment\Contracts\PaymentDriver;
-
 /**
  * Resolves a payment type key (e.g. 'stripe', 'cash-on-delivery') to its
- * registered PaymentDriver — extracted out of CheckoutService so both it
- * and anything else needing the same lookup (e.g. a listener reacting to
- * OrderPlaced, which has no reason to depend on Checkout's own service)
- * share one implementation instead of duplicating this config read.
+ * 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
 {
@@ -20,7 +25,7 @@ class PaymentDriverResolver
      * can filter unresolvable types silently rather than treating "not
      * registered" as an error condition when just checking availability.
      */
-    public function resolve(string $type): ?PaymentDriver
+    public function resolve(string $type): ?object
     {
         $driverClass = config("lunar.payments.types.{$type}.payment_driver");