📄 PaymentGatewayInterface.php

<?php

namespace App\Contracts;

use App\Modules\Order\Models\Order;

/**
 * PaymentGatewayInterface
 *
 * Every payment gateway (COD, eSewa, Khalti, Stripe…) must implement this.
 * Phase 1: only CashOnDeliveryGateway is wired up.
 * Phase 2+: eSewa / Khalti / IME Pay / Connect IPS.
 */
interface PaymentGatewayInterface
{
    /**
     * Return the gateway's unique identifier (used in DB and config).
     * e.g. 'cod', 'esewa', 'khalti', 'stripe'
     */
    public function getName(): string;

    /**
     * Human-readable label shown in checkout.
     */
    public function getLabel(): string;

    /**
     * Initiate payment. Returns a redirect URL or gateway payload
     * needed by the frontend to start the payment flow.
     *
     * @return array{redirect_url?: string, form_data?: array, payment_id?: string}
     */
    public function initiate(Order $order, array $options = []): array;

    /**
     * Verify and confirm a payment after gateway callback/webhook.
     * Returns true on success, throws PaymentVerificationException on failure.
     */
    public function verify(Order $order, array $payload): bool;

    /**
     * Issue a full or partial refund.
     *
     * @param  float|null  $amount  null = full refund
     */
    public function refund(Order $order, ?float $amount = null, string $reason = ''): bool;

    /**
     * Whether this gateway supports webhook-based status updates.
     */
    public function supportsWebhooks(): bool;

    /**
     * Validate and extract data from an incoming webhook payload.
     * Called by the generic WebhookController.
     */
    public function handleWebhook(array $payload): void;
}