core/src/Payment/Contracts/SupportsCaptures.php

<?php

namespace Modules\Core\Payment\Contracts;

use Modules\Core\Payment\DTOs\PaymentResult;

/**
 * Settles a PRIOR SupportsAuthorization::authorize() hold — only ever
 * valid against a reference that call (or a HandlesPaymentCallback
 * resolving it) produced, never called standalone. A driver with no
 * authorize-then-settle model at all (most redirect/wallet gateways, any
 * offline driver) never implements this — it settles everything through
 * SupportsPay::pay() in one step instead.
 *
 * Dispatches Modules\Core\Payment\Events\PaymentCaptured or
 * PaymentCaptureFailed — the same terminal events SupportsPay::pay()
 * produces, since "money has been captured" is the same business fact
 * regardless of which path reached it.
 */
interface SupportsCaptures
{
    /**
     * $reference is the identifier SupportsAuthorization::authorize()
     * returned (PaymentResult::$reference) for the hold being settled.
     *
     * $amount lets a driver capture less than the full authorized amount
     * (e.g. shipping less than ordered) — up to the driver/gateway
     * whether a partial capture also releases the remainder or leaves it
     * capturable again later (multicapture-style gateways).
     *
     * @param  array<string, mixed>  $context
     */
    public function capture(string $reference, int $amount, array $context = []): PaymentResult;
}