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

src/Payment/DTOs/PaymentContinuation.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Modules\Core\Payment\DTOs;
+
+use Modules\Core\Payment\Enums\PaymentContinuationType;
+
+/**
+ * What a caller does next with a Pending PaymentResult, gateway-agnostic —
+ * see PaymentContinuationType for the two shapes. Deliberately minimal:
+ * this is NOT a return to the deleted PaymentInitiation DTO (which also
+ * carried mode/reference/meta) — reference already lives on PaymentResult
+ * itself, and mode is now this DTO's own $type.
+ */
+final class PaymentContinuation
+{
+    public function __construct(
+        public readonly PaymentContinuationType $type,
+        public readonly string $value,
+    ) {}
+}

src/Payment/DTOs/PaymentResult.php

@@ -47,6 +47,11 @@ final class PaymentResult
      *   normalize into anything above.
      * @param  $meta  driver-specific extras that don't fit the normalized
      *   fields above (e.g. a card's last four digits).
+     * @param  $continuation  only meaningful when $status is Pending —
+     *   what the caller does next (a redirect URL, a client secret for
+     *   frontend JS), gateway-agnostic. Null for every other status, and
+     *   for any driver whose pay()/authorize() never returns Pending
+     *   (e.g. OfflinePaymentDriver).
      */
     public function __construct(
         public readonly PaymentResultStatus $status,
@@ -56,5 +61,6 @@ final class PaymentResult
         public readonly bool $retriable = false,
         public readonly array $raw = [],
         public readonly array $meta = [],
+        public readonly ?PaymentContinuation $continuation = null,
     ) {}
 }