Feat: Payment Restructuring to be fully event-driven

src/Payment/Contracts/SupportsPay.php

@@ -2,6 +2,7 @@
 
 namespace Modules\Core\Payment\Contracts;
 
+use Lunar\DataTypes\Price;
 use Modules\Core\Payment\DTOs\PaymentResult;
 
 /**
@@ -27,10 +28,16 @@ interface SupportsPay
      * one type, because a driver shared across several types needs it to
      * look up that type's own config.
      *
-     * $data carries whatever the gateway needs (amount, currency, customer
-     * details, a payment method token) — the caller's responsibility to
-     * assemble, since a driver has no notion of a cart or order to pull
-     * them from itself.
+     * $amount is required, not optional data a caller might omit — there
+     * is no way to process a payment without knowing what to charge.
+     * Lunar's own Price (bundling its own currency) — the same money
+     * representation every other Payment contract method takes/returns,
+     * see PaymentResult's own docblock.
+     *
+     * $data carries whatever ELSE the gateway needs (customer details, a
+     * payment method token) — the caller's responsibility to assemble,
+     * since a driver has no notion of a cart or order to pull them from
+     * itself.
      *
      * $context is opaque to the driver — carried through untouched into
      * whichever Payment event this call (or a later handleCallback()
@@ -41,5 +48,5 @@ interface SupportsPay
      * @param  array<string, mixed>  $data
      * @param  array<string, mixed>  $context
      */
-    public function pay(string $type, array $data, array $context = []): PaymentResult;
-}
+    public function pay(string $type, Price $amount, array $data = [], array $context = []): PaymentResult;
+}