<?php

namespace Modules\Core\Payment\Contracts;

use Lunar\DataTypes\Price;
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 is Lunar's own Price (never a gateway's own minor-unit
     * scale — see PaymentResult's docblock), allowing a partial refund; a
     * gateway may allow multiple partial refunds against one settlement,
     * up to its own total. Required explicitly, same reasoning as
     * SupportsCaptures::capture()'s own $amount.
     *
     * @param  array<string, mixed>  $context
     */
    public function refund(string $reference, Price $amount, array $context = []): PaymentResult;
}