Feat: Payment Restructuring to be fully event-driven

src/Payment/Contracts/SupportsCaptures.php

@@ -2,6 +2,7 @@
 
 namespace Modules\Core\Payment\Contracts;
 
+use Lunar\DataTypes\Price;
 use Modules\Core\Payment\DTOs\PaymentResult;
 
 /**
@@ -23,12 +24,16 @@ interface SupportsCaptures
      * $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).
+     * $amount is Lunar's own Price (never a gateway's own minor-unit
+     * scale — see PaymentResult's docblock), and 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). Required explicitly, not derived by
+     * the driver from a live gateway lookup — the caller (whatever placed
+     * the original authorize() call) already knows it.
      *
      * @param  array<string, mixed>  $context
      */
-    public function capture(string $reference, int $amount, array $context = []): PaymentResult;
+    public function capture(string $reference, Price $amount, array $context = []): PaymentResult;
 }