<?php

namespace App\Contracts;

interface PaymentGatewayInterface
{
    /**
     * Initialiser un paiement
     *
     * @param array $payload Données de paiement (montant, devise, email, etc.)
     * @return array Réponse du gateway (transaction_id, redirect_url, etc.)
     */
    public function initiate(array $payload): array;

    /**
     * Vérifier le statut d'un paiement
     *
     * @param string $reference Référence de la transaction
     * @return array Statut (success, pending, failed) et données associées
     */
    public function verify(string $reference): array;

    /**
     * Rembourser une transaction
     *
     * @param string $reference Référence de la transaction
     * @param float|null $amount Montant à rembourser (null = total)
     * @return array Statut du remboursement
     */
    public function refund(string $reference, ?float $amount = null): array;

    /**
     * Valider les paramètres de configuration
     *
     * @return bool
     * @throws \Exception Si configuration invalide
     */
    public function validateConfig(): bool;

    /**
     * Retourner le nom du gateway
     *
     * @return string
     */
    public function getName(): string;
}
