<?php

declare(strict_types=1);

namespace apexl\Io\modules\payment\Contract;

use apexl\Io\modules\payment\Dto\RefundResult;

/**
 * Gateway supports refunds against previously-captured payments.
 *
 * Most gateways do but a few (notably some BNPL providers) don't allow
 * programmatic refunds — separating into its own interface lets consumers
 * gate refund UI on capability detection.
 */
interface RefundableGatewayInterface
{
    /**
     * Refund a previously-captured payment. Pass `$amountCents = null` for
     * a full refund; pass an integer for a partial refund (must be less
     * than the original amount minus prior partial refunds).
     */
    public function refund(
        string $gatewayPaymentRef,
        ?int   $amountCents = null,
        ?string $reason = null,
    ): RefundResult;
}
