<?php

namespace App\Services\Payments;

use App\Models\Payment;
use Illuminate\Http\Request;

/**
 * Contract every payment provider must satisfy (PRD 73).
 *
 * Application code talks to PaymentService, which talks to one of these.
 * Nothing outside this namespace may reference a specific provider.
 */
interface PaymentGatewayInterface
{
    /** Machine name used in config, the payments table and webhook routes. */
    public function name(): string;

    /** Human label shown to the applicant when choosing how to pay. */
    public function label(): string;

    /**
     * Begin a payment. Returns where to send the applicant next and any
     * provider references worth persisting.
     */
    public function initializePayment(Payment $payment, array $context = []): PaymentInitialization;

    /**
     * Ask the provider what actually happened. This is the authority on
     * whether a payment succeeded — never the browser redirect (PRD 19).
     */
    public function verifyPayment(Payment $payment): PaymentVerification;

    /**
     * Translate an inbound webhook into a normalised result, rejecting
     * anything whose signature does not check out.
     */
    public function handleWebhook(Request $request): WebhookResult;

    public function refundPayment(Payment $payment, ?float $amount = null): bool;
}
