<?php

namespace App\Contracts;

use App\Models\Order;

interface PaymentGatewayInterface
{
    /**
     * Create a payment session and return the gateway's redirect URL.
     *
     * @return array{ session_id: string, redirect_url: string }
     */
    public function createSession(Order $order, string $returnUrl, string $cancelUrl): array;

    /**
     * Verify a completed payment session and return 'paid', 'pending', or 'failed'.
     */
    public function getSessionStatus(string $sessionId): string;

    /**
     * Validate an incoming webhook request.
     * Returns the gateway-specific order reference (payment_reference) on success.
     */
    public function handleWebhook(array $payload, string $rawBody, string $signature): ?string;
}
