core/src/Payment/Contracts/SupportsVoids.php

<?php

namespace Modules\Core\Payment\Contracts;

use Lunar\DataTypes\Price;
use Modules\Core\Payment\DTOs\PaymentResult;

/**
 * Cancels a PRIOR SupportsAuthorization::authorize() hold WITHOUT
 * settling it — the "actually, never mind" exit SupportsCaptures::capture()
 * doesn't take. No funds ever moved, so this is not a refund: there is
 * nothing to give back, only a hold to release early (rather than letting
 * it simply expire on its own).
 *
 * Dispatches Modules\Core\Payment\Events\PaymentVoided or
 * PaymentVoidFailed.
 */
interface SupportsVoids
{
    /**
     * $reference is the identifier SupportsAuthorization::authorize()
     * returned for the hold being released.
     *
     * $amount is the authorized amount being released — Lunar's own
     * Price, same as every other Payment contract method (see
     * PaymentResult's own docblock). Required explicitly: the caller
     * (whatever placed the original authorize() call) already knows it,
     * same reasoning as SupportsCaptures::capture()'s own $amount — a
     * driver shouldn't need a live gateway lookup just to know what it's
     * releasing.
     *
     * @param  array<string, mixed>  $context
     */
    public function void(string $reference, Price $amount, array $context = []): PaymentResult;
}