Feature: Abstraction on Payments based on their operations

src/Payment/Contracts/SupportsRefunds.php

@@ -2,23 +2,30 @@
 
 namespace Modules\Core\Payment\Contracts;
 
-use Lunar\Models\Order;
-use Modules\Core\Payment\DataTransferObjects\RefundResult;
+use Modules\Core\Payment\DTOs\PaymentResult;
 
 /**
- * Optional capability for payment drivers whose gateway supports refunding
- * a prior charge. Drivers without a refund API (or that never got that far
- * — e.g. an offline/manual driver) simply don't implement it. Mirrors
- * Shipping\Contracts\SupportsTracking's opt-in shape.
+ * Reverses settled funds — independent of SupportsCaptures/SupportsVoids:
+ * a driver that only ever settles via SupportsPay::pay() (no separate
+ * authorize step) can still implement this, since a refund targets money
+ * already taken regardless of how it got taken. A driver implements this
+ * whenever its gateway exposes any refund capability at all, whether or
+ * not it also supports authorize-then-capture.
+ *
+ * Dispatches Modules\Core\Payment\Events\PaymentRefunded or
+ * PaymentRefundFailed.
  */
 interface SupportsRefunds
 {
     /**
-     * $reference is the gateway's own identifier for the charge being
-     * refunded (e.g. a Viva Wallet transaction id) — not a Lunar
-     * Transaction model, since not every gateway's refund flow maps
-     * cleanly onto one. $amount is in the currency's minor unit, same
-     * convention as Lunar\Base\Casts\Price.
+     * $reference is the identifier the original SupportsPay::pay() or
+     * SupportsCaptures::capture() call returned for the settled funds
+     * being refunded.
+     *
+     * $amount allows a partial refund; a gateway may allow multiple
+     * partial refunds against one settlement, up to its own total.
+     *
+     * @param  array<string, mixed>  $context
      */
-    public function refund(Order $order, string $reference, int $amount, ?string $notes = null): RefundResult;
+    public function refund(string $reference, int $amount, array $context = []): PaymentResult;
 }