Feat: Payment Restructuring to be fully event-driven

src/Payment/DTOs/PaymentResult.php

@@ -2,6 +2,7 @@
 
 namespace Modules\Core\Payment\DTOs;
 
+use Lunar\DataTypes\Price;
 use Modules\Core\Payment\Enums\PaymentResultStatus;
 
 /**
@@ -23,6 +24,13 @@ use Modules\Core\Payment\Enums\PaymentResultStatus;
 final class PaymentResult
 {
     /**
+     * @param  $amount  Lunar's own money type (Lunar\DataTypes\Price —
+     *   integer minor units bundled with its Currency), the SAME
+     *   representation every contract method takes/returns — never a
+     *   gateway's own minor-unit scale. Each driver converts at its own
+     *   boundary (e.g. StripeManager::toStripeAmount()/fromStripeAmount())
+     *   before calling out to, or after reading back from, its gateway —
+     *   Payment itself only ever speaks Lunar's Price.
      * @param  $failureReason  a human-readable reason, only meaningful
      *   when $status is Failed — the driver's own normalization of
      *   whatever the gateway called it (Stripe's decline_code message,
@@ -43,7 +51,7 @@ final class PaymentResult
     public function __construct(
         public readonly PaymentResultStatus $status,
         public readonly string $reference,
-        public readonly int $amount,
+        public readonly Price $amount,
         public readonly ?string $failureReason = null,
         public readonly bool $retriable = false,
         public readonly array $raw = [],