<?php

namespace App\Libraries\PaymentGateways;

/**
 * Common contract so PaymentService never branches on gateway type
 * (see 05-saas-architecture.md §7). Every adapter below implements this
 * the same way regardless of the underlying provider's API shape.
 */
interface PaymentGatewayInterface
{
    /**
     * Initiates a charge. Returns a redirect URL (for redirect-flow
     * gateways like JazzCash/Easypaisa/PayPal) or a client secret / charge
     * confirmation (for API-flow gateways like Stripe) — normalized into
     * a single associative shape so PaymentService doesn't need to know
     * which kind of flow it's dealing with.
     *
     * @return array{status:string, redirect_url:?string, client_secret:?string, gateway_reference:?string}
     */
    public function charge(float $amount, string $currency, array $metadata = []): array;

    /**
     * Verifies and processes an inbound webhook payload. Returns a
     * normalized result the PaymentService can act on uniformly.
     *
     * @return array{verified:bool, gateway_transaction_id:?string, status:?string, raw:array}
     */
    public function verifyWebhook(string $rawPayload, array $headers): array;

    public function refund(string $gatewayTransactionId, float $amount): array;

    public function getStatus(string $gatewayTransactionId): array;
}
