Feature: Abstraction on Payments based on their operations

src/Payment/Contracts/SupportsCaptures.php

@@ -2,22 +2,33 @@
 
 namespace Modules\Core\Payment\Contracts;
 
-use Lunar\Models\Order;
-use Modules\Core\Payment\DataTransferObjects\CaptureResult;
+use Modules\Core\Payment\DTOs\PaymentResult;
 
 /**
- * Optional capability for payment drivers whose gateway supports a
- * separate authorize-then-capture step. Many redirect/wallet-style
- * gateways (Viva Wallet included, for most flows) charge in full at
- * checkout and never need this — SupportsRefunds is the one they're more
- * likely to implement instead.
+ * Settles a PRIOR SupportsAuthorization::authorize() hold — only ever
+ * valid against a reference that call (or a HandlesPaymentCallback
+ * resolving it) produced, never called standalone. A driver with no
+ * authorize-then-settle model at all (most redirect/wallet gateways, any
+ * offline driver) never implements this — it settles everything through
+ * SupportsPay::pay() in one step instead.
+ *
+ * Dispatches Modules\Core\Payment\Events\PaymentCaptured or
+ * PaymentCaptureFailed — the same terminal events SupportsPay::pay()
+ * produces, since "money has been captured" is the same business fact
+ * regardless of which path reached it.
  */
 interface SupportsCaptures
 {
     /**
-     * $reference is the gateway's own identifier for the authorized charge
-     * — see SupportsRefunds::refund() for why this isn't a Lunar
-     * Transaction. $amount is in the currency's minor unit.
+     * $reference is the identifier SupportsAuthorization::authorize()
+     * returned (PaymentResult::$reference) for the hold being settled.
+     *
+     * $amount lets a driver capture less than the full authorized amount
+     * (e.g. shipping less than ordered) — up to the driver/gateway
+     * whether a partial capture also releases the remainder or leaves it
+     * capturable again later (multicapture-style gateways).
+     *
+     * @param  array<string, mixed>  $context
      */
-    public function capture(Order $order, string $reference, int $amount, ?string $notes = null): CaptureResult;
-}
+    public function capture(string $reference, int $amount, array $context = []): PaymentResult;
+}