Feature: Abstraction on Payments based on their operations

src/Payment/Contracts/HandlesPaymentCallback.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Modules\Core\Payment\Contracts;
+
+use Modules\Core\Payment\DTOs\PaymentResult;
+
+/**
+ * The async counterpart to SupportsPay::pay()/SupportsAuthorization::
+ * authorize() — implemented only by a driver whose gateway can't resolve
+ * one of those synchronously (a redirect the shopper completes elsewhere,
+ * a webhook that arrives later). A driver whose pay()/authorize() always
+ * returns a terminal PaymentResult (Succeeded/Failed) in the same call
+ * never implements this — there is nothing left to call back.
+ *
+ * Resolves into the SAME events the original pay()/authorize() call would
+ * have produced had it resolved synchronously — PaymentCaptured/
+ * PaymentCaptureFailed for a pending pay(), PaymentAuthorized/
+ * PaymentAuthorizationFailed for a pending authorize(). Which pair
+ * applies is up to the driver to track (e.g. against whatever it stored
+ * when the original call returned Pending), not something this method's
+ * signature can express generically.
+ */
+interface HandlesPaymentCallback
+{
+    /**
+     * $reference is the gateway's own identifier for the pending attempt
+     * (the same value the original pay()/authorize() call returned via
+     * PaymentResult::$reference) — how the driver finds which attempt
+     * this callback belongs to.
+     *
+     * $data carries whatever the callback/webhook payload contains
+     * (Stripe: ['payment_intent' => $id], a redirect-based provider: its
+     * query params or POST body) — passed explicitly by the caller rather
+     * than the driver reaching into the global request(), so this works
+     * the same whether it's called from a synchronous HTTP request or an
+     * async webhook job with no active request at all.
+     *
+     * $context is opaque to the driver, carried through untouched into
+     * whichever Payment event this callback produces — see SupportsPay::
+     * pay()'s own $context param for the full reasoning. A driver that
+     * needs the ORIGINAL context from the pay()/authorize() call (a
+     * webhook's own payload carries none of its own) must have persisted
+     * it itself when that call returned Pending — Payment provides no
+     * storage for this.
+     *
+     * @param  array<string, mixed>  $data
+     * @param  array<string, mixed>  $context
+     */
+    public function handleCallback(string $reference, array $data, array $context = []): PaymentResult;
+}