from abc import ABC, abstractmethod
from typing import Any, Optional


class PaymentGateway(ABC):
    """Abstract interface for third-party payment gateways (Razorpay, Stripe, etc.)."""

    @abstractmethod
    async def create_order(
        self,
        amount: int,
        currency: str,
        receipt: str,
        notes: dict[str, Any],
        idempotency_key: Optional[str] = None,
    ) -> dict[str, Any]:
        """Creates a checkout order / payment intent with the gateway."""
        pass

    @abstractmethod
    def verify_payment_signature(
        self,
        order_id: str,
        payment_id: str,
        signature: str,
    ) -> bool:
        """Verifies frontend payment completion signature server-side."""
        pass

    @abstractmethod
    def verify_webhook_signature(
        self,
        payload: bytes,
        signature: str,
        headers: Optional[dict[str, str]] = None,
    ) -> bool:
        """Verifies incoming webhook payload authenticity using HMAC."""
        pass

    @abstractmethod
    async def create_refund(
        self,
        payment_id: str,
        amount: int,
        currency: str,
        reason: str,
    ) -> dict[str, Any]:
        """Initiates a refund with the gateway."""
        pass
