<?php

namespace Modules\Core\Payment\Contracts;

use Modules\Core\Payment\DTOs\PaymentResult;

/**
 * The async counterpart to SupportsPay::pay()/SupportsAuthorization::
 * authorize() — implemented only by a driver whose gateway can't resolve
 * one of those synchronously (a redirect the shopper completes elsewhere,
 * a webhook that arrives later). A driver whose pay()/authorize() always
 * returns a terminal PaymentResult (Succeeded/Failed) in the same call
 * never implements this — there is nothing left to call back.
 *
 * Resolves into the SAME events the original pay()/authorize() call would
 * have produced had it resolved synchronously — PaymentCaptured/
 * PaymentCaptureFailed for a pending pay(), PaymentAuthorized/
 * PaymentAuthorizationFailed for a pending authorize(). Which pair
 * applies is up to the driver to track (e.g. against whatever it stored
 * when the original call returned Pending), not something this method's
 * signature can express generically.
 */
interface HandlesPaymentCallback
{
    /**
     * $reference is the gateway's own identifier for the pending attempt
     * (the same value the original pay()/authorize() call returned via
     * PaymentResult::$reference) — how the driver finds which attempt
     * this callback belongs to.
     *
     * $data carries whatever the callback/webhook payload contains
     * (Stripe: ['payment_intent' => $id], a redirect-based provider: its
     * query params or POST body) — passed explicitly by the caller rather
     * than the driver reaching into the global request(), so this works
     * the same whether it's called from a synchronous HTTP request or an
     * async webhook job with no active request at all.
     *
     * $context is opaque to the driver, carried through untouched into
     * whichever Payment event this callback produces — see SupportsPay::
     * pay()'s own $context param for the full reasoning. A driver that
     * needs the ORIGINAL context from the pay()/authorize() call (a
     * webhook's own payload carries none of its own) must have persisted
     * it itself when that call returned Pending — Payment provides no
     * storage for this.
     *
     * @param  array<string, mixed>  $data
     * @param  array<string, mixed>  $context
     */
    public function handleCallback(string $reference, array $data, array $context = []): PaymentResult;
}