core/src/Payment/Contracts/SupportsRefunds.php

<?php

namespace Modules\Core\Payment\Contracts;

use Modules\Core\Payment\DTOs\PaymentResult;

/**
 * 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 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(string $reference, int $amount, array $context = []): PaymentResult;
}