Feature: Abstraction on Payments based on their operations

src/Payment/Contracts/SupportsAuthorization.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Modules\Core\Payment\Contracts;
+
+use Modules\Core\Payment\DTOs\PaymentResult;
+
+/**
+ * A driver's hold-only operation (Mastercard's "Authorize", Nexi's
+ * ActionType::PREAUTH(), Stripe's capture_method=manual) — places a hold
+ * on the customer's payment method without moving any funds. Only a
+ * driver that also implements SupportsCaptures/SupportsVoids can do
+ * anything with the resulting hold afterward; implementing this alone
+ * with neither of those would leave the hold to simply expire
+ * (typically ~7 days, gateway-dependent) with no way to settle or release
+ * it early.
+ *
+ * A driver capable of both authorize-then-settle AND an atomic charge
+ * (most card gateways) implements this alongside SupportsPay — which one
+ * gets called for a given payment attempt is the CALLER's choice (a
+ * policy decision), not something this driver decides for itself.
+ *
+ * Dispatches Modules\Core\Payment\Events\PaymentAuthorized or
+ * PaymentAuthorizationFailed based on the returned PaymentResult's status,
+ * unless $result->status is Pending — see SupportsPay's docblock for the
+ * same async-resolution note.
+ */
+interface SupportsAuthorization
+{
+    /**
+     * Same $type/$data/$context reasoning as SupportsPay::pay().
+     *
+     * @param  array<string, mixed>  $data
+     * @param  array<string, mixed>  $context
+     */
+    public function authorize(string $type, array $data, array $context = []): PaymentResult;
+}