Feature: Abstraction on Payments based on their operations

src/Payment/Events/PaymentCaptured.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Modules\Core\Payment\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Modules\Core\Payment\DTOs\PaymentResult;
+
+/**
+ * The one "money has actually been taken" event, dispatched from either of
+ * two different call paths that end at the same business fact:
+ *   - SupportsPay::pay() — an atomic authorize+capture gateway call
+ *     (Mastercard's "Pay", Stripe's capture_method=automatic, an offline
+ *     driver's immediate success).
+ *   - SupportsCaptures::capture() — settling a PRIOR authorize() hold.
+ * Whether the money moved in one gateway call or two is a driver-internal
+ * detail; a listener reacting to "a payment has been captured" never
+ * needs to know or care which path produced this event.
+ */
+class PaymentCaptured
+{
+    use Dispatchable;
+
+    /**
+     * @param  array<string, mixed>  $context
+     */
+    public function __construct(
+        public readonly string $type,
+        public readonly PaymentResult $result,
+        public readonly array $context = [],
+    ) {}
+}