pay-engine 0.1.0__py3-none-any.whl

pay_engine/__init__.py

@@ -0,0 +1,168 @@
+"""
+pay-engine: All-in-one payment engine for Uzbekistan.
+Supports Payme, Click, and Uzum Bank with one-liners, Telegram buttons, and auto-charge.
+"""
+
+from typing import Any, Dict, List, Optional, Union
+
+from .core.config import ClickConfig, PaymeConfig, UzumConfig
+from .core.exceptions import (
+    CardTokenError,
+    ConfigurationError,
+    InvalidAmountError,
+    OrderNotFoundError,
+    PayEngineError,
+    SignatureVerificationError,
+)
+from .core.models import (
+    CardChargeRequest,
+    CardChargeResult,
+    PaymentRequest,
+    TransactionStatus,
+    WebhookResult,
+)
+from .providers.click.client import ClickClient
+from .providers.click.handler import ClickHandler
+from .providers.payme.client import PaymeClient
+from .providers.payme.handler import PaymeHandler
+from .providers.uzum.client import UzumClient
+from .providers.uzum.handler import UzumHandler
+
+__version__ = "0.1.0"
+
+
+class _PaymeProxy:
+    """Convenience helper for Payme one-liners."""
+
+    @staticmethod
+    def link(
+        amount: float,
+        order_id: Union[str, int],
+        return_url: Optional[str] = None,
+        merchant_id: Optional[str] = None,
+        test_mode: Optional[bool] = None,
+        **kwargs: Any,
+    ) -> str:
+        client = PaymeClient(merchant_id=merchant_id, test_mode=test_mode)
+        return client.create_link(amount=amount, order_id=order_id, return_url=return_url, **kwargs)
+
+    @staticmethod
+    def charge(
+        card_token: str,
+        amount: float,
+        order_id: Union[str, int],
+        secret_key: Optional[str] = None,
+        description: Optional[str] = None,
+        **kwargs: Any,
+    ) -> CardChargeResult:
+        client = PaymeClient(secret_key=secret_key)
+        return client.charge_card(card_token=card_token, amount=amount, order_id=order_id, description=description, **kwargs)
+
+
+class _ClickProxy:
+    """Convenience helper for Click one-liners."""
+
+    @staticmethod
+    def link(
+        amount: float,
+        order_id: Union[str, int],
+        return_url: Optional[str] = None,
+        service_id: Optional[str] = None,
+        merchant_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> str:
+        client = ClickClient(service_id=service_id, merchant_id=merchant_id)
+        return client.create_link(amount=amount, order_id=order_id, return_url=return_url, **kwargs)
+
+    @staticmethod
+    def charge(
+        card_token: str,
+        amount: float,
+        order_id: Union[str, int],
+        service_id: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        merchant_user_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> CardChargeResult:
+        client = ClickClient(service_id=service_id, secret_key=secret_key, merchant_user_id=merchant_user_id)
+        return client.charge_card(card_token=card_token, amount=amount, order_id=order_id, **kwargs)
+
+
+class _UzumProxy:
+    """Convenience helper for Uzum Bank one-liners."""
+
+    @staticmethod
+    def link(
+        amount: float,
+        order_id: Union[str, int],
+        return_url: Optional[str] = None,
+        shop_id: Optional[str] = None,
+        **kwargs: Any,
+    ) -> str:
+        client = UzumClient(shop_id=shop_id)
+        return client.create_link(amount=amount, order_id=order_id, return_url=return_url, **kwargs)
+
+
+class PayEngine:
+    """Unified master engine for payments."""
+
+    def __init__(
+        self,
+        payme_merchant_id: Optional[str] = None,
+        payme_secret_key: Optional[str] = None,
+        click_service_id: Optional[str] = None,
+        click_merchant_id: Optional[str] = None,
+        click_secret_key: Optional[str] = None,
+        uzum_shop_id: Optional[str] = None,
+        uzum_secret_key: Optional[str] = None,
+        test_mode: bool = False,
+    ):
+        self.payme = PaymeClient(merchant_id=payme_merchant_id, secret_key=payme_secret_key, test_mode=test_mode) if (payme_merchant_id or PaymeConfig().merchant_id) else None
+        self.click = ClickClient(service_id=click_service_id, merchant_id=click_merchant_id, secret_key=click_secret_key) if (click_service_id or ClickConfig().service_id) else None
+        self.uzum = UzumClient(shop_id=uzum_shop_id, secret_key=uzum_secret_key) if (uzum_shop_id or UzumConfig().shop_id) else None
+
+    def get_links(
+        self,
+        amount: float,
+        order_id: Union[str, int],
+        return_url: Optional[str] = None,
+    ) -> Dict[str, str]:
+        """Returns checkout URLs for all configured providers."""
+        links = {}
+        if self.payme:
+            links["payme"] = self.payme.create_link(amount=amount, order_id=order_id, return_url=return_url)
+        if self.click:
+            links["click"] = self.click.create_link(amount=amount, order_id=order_id, return_url=return_url)
+        if self.uzum:
+            links["uzum"] = self.uzum.create_link(amount=amount, order_id=order_id, return_url=return_url)
+        return links
+
+
+# Public helper instances
+payme = _PaymeProxy()
+click = _ClickProxy()
+uzum = _UzumProxy()
+
+__all__ = [
+    "PayEngine",
+    "payme",
+    "click",
+    "uzum",
+    "PaymeClient",
+    "PaymeHandler",
+    "ClickClient",
+    "ClickHandler",
+    "UzumClient",
+    "UzumHandler",
+    "PayEngineError",
+    "ConfigurationError",
+    "SignatureVerificationError",
+    "InvalidAmountError",
+    "OrderNotFoundError",
+    "CardTokenError",
+    "TransactionStatus",
+    "PaymentRequest",
+    "WebhookResult",
+    "CardChargeRequest",
+    "CardChargeResult",
+]

pay_engine/core/__init__.py

@@ -0,0 +1,35 @@
+"""Core module for pay-engine."""
+
+from .config import ClickConfig, PaymeConfig, UzumConfig
+from .exceptions import (
+    CardTokenError,
+    ConfigurationError,
+    InvalidAmountError,
+    OrderNotFoundError,
+    PayEngineError,
+    SignatureVerificationError,
+)
+from .models import (
+    CardChargeRequest,
+    CardChargeResult,
+    PaymentRequest,
+    TransactionStatus,
+    WebhookResult,
+)
+
+__all__ = [
+    "PayEngineError",
+    "ConfigurationError",
+    "SignatureVerificationError",
+    "InvalidAmountError",
+    "OrderNotFoundError",
+    "CardTokenError",
+    "TransactionStatus",
+    "PaymentRequest",
+    "WebhookResult",
+    "CardChargeRequest",
+    "CardChargeResult",
+    "PaymeConfig",
+    "ClickConfig",
+    "UzumConfig",
+]

pay_engine/core/config.py

@@ -0,0 +1,74 @@
+"""Configuration management for pay-engine."""
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+
+def _load_env_file():
+    """Simple parser to load .env file if it exists, without needing python-dotenv."""
+    env_path = os.path.join(os.getcwd(), ".env")
+    if os.path.isfile(env_path):
+        try:
+            with open(env_path, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line or line.startswith("#") or "=" not in line:
+                        continue
+                    key, val = line.split("=", 1)
+                    key = key.strip()
+                    val = val.strip().strip("'\"")
+                    if key not in os.environ:
+                        os.environ[key] = val
+        except Exception:
+            pass
+
+
+# Automatically attempt to load .env on module import
+_load_env_file()
+
+
+@dataclass
+class PaymeConfig:
+    merchant_id: Optional[str] = None
+    secret_key: Optional[str] = None
+    test_mode: bool = False
+
+    def __post_init__(self):
+        if not self.merchant_id:
+            self.merchant_id = os.getenv("PAYME_MERCHANT_ID")
+        if not self.secret_key:
+            self.secret_key = os.getenv("PAYME_SECRET_KEY")
+        test_env = os.getenv("PAYME_TEST_MODE", "").lower()
+        if test_env in ("1", "true", "yes"):
+            self.test_mode = True
+
+
+@dataclass
+class ClickConfig:
+    service_id: Optional[str] = None
+    merchant_id: Optional[str] = None
+    secret_key: Optional[str] = None
+    merchant_user_id: Optional[str] = None
+
+    def __post_init__(self):
+        if not self.service_id:
+            self.service_id = os.getenv("CLICK_SERVICE_ID")
+        if not self.merchant_id:
+            self.merchant_id = os.getenv("CLICK_MERCHANT_ID")
+        if not self.secret_key:
+            self.secret_key = os.getenv("CLICK_SECRET_KEY")
+        if not self.merchant_user_id:
+            self.merchant_user_id = os.getenv("CLICK_MERCHANT_USER_ID")
+
+
+@dataclass
+class UzumConfig:
+    shop_id: Optional[str] = None
+    secret_key: Optional[str] = None
+
+    def __post_init__(self):
+        if not self.shop_id:
+            self.shop_id = os.getenv("UZUM_SHOP_ID")
+        if not self.secret_key:
+            self.secret_key = os.getenv("UZUM_SECRET_KEY")

pay_engine/core/exceptions.py

@@ -0,0 +1,30 @@
+"""Exceptions for pay-engine."""
+
+class PayEngineError(Exception):
+    """Base exception for all pay-engine errors."""
+    pass
+
+
+class ConfigurationError(PayEngineError):
+    """Raised when provider credentials or configurations are missing or invalid."""
+    pass
+
+
+class SignatureVerificationError(PayEngineError):
+    """Raised when an incoming webhook signature or authentication fails."""
+    pass
+
+
+class InvalidAmountError(PayEngineError):
+    """Raised when transaction amount is invalid, zero, or negative."""
+    pass
+
+
+class OrderNotFoundError(PayEngineError):
+    """Raised when an order or transaction ID cannot be found."""
+    pass
+
+
+class CardTokenError(PayEngineError):
+    """Raised when card tokenization, binding, or auto-charge fails."""
+    pass

pay_engine/core/models.py

@@ -0,0 +1,51 @@
+"""Data models for pay-engine."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, Optional
+
+
+class TransactionStatus(str, Enum):
+    PENDING = "pending"
+    PAID = "paid"
+    CANCELLED = "cancelled"
+    FAILED = "failed"
+
+
+@dataclass
+class PaymentRequest:
+    amount: float
+    order_id: str
+    description: Optional[str] = None
+    return_url: Optional[str] = None
+    extra_params: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class WebhookResult:
+    is_paid: bool
+    provider: str
+    order_id: str
+    amount: float
+    transaction_id: Optional[str] = None
+    status: TransactionStatus = TransactionStatus.PENDING
+    raw_data: Dict[str, Any] = field(default_factory=dict)
+    response_data: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class CardChargeRequest:
+    card_token: str
+    amount: float
+    order_id: str
+    description: Optional[str] = None
+
+
+@dataclass
+class CardChargeResult:
+    success: bool
+    order_id: str
+    amount: float
+    transaction_id: Optional[str] = None
+    message: Optional[str] = None
+    raw_data: Dict[str, Any] = field(default_factory=dict)

pay_engine/integrations/__init__.py

@@ -0,0 +1,14 @@
+"""Integrations package for pay-engine."""
+
+from .fastapi import click_router, pay_router, payme_router, uzum_router
+from .telegram import format_amount, get_payment_links, payment_buttons
+
+__all__ = [
+    "payme_router",
+    "click_router",
+    "uzum_router",
+    "pay_router",
+    "payment_buttons",
+    "get_payment_links",
+    "format_amount",
+]

pay_engine/integrations/fastapi.py

@@ -0,0 +1,137 @@
+"""FastAPI integration for pay-engine."""
+
+import inspect
+from typing import Any, Callable, Optional
+
+from ..providers.click.handler import ClickHandler
+from ..providers.payme.handler import PaymeHandler
+from ..providers.uzum.handler import UzumHandler
+
+try:
+    from fastapi import APIRouter, Request, Response
+    from fastapi.responses import JSONResponse
+    FASTAPI_AVAILABLE = True
+except ImportError:
+    FASTAPI_AVAILABLE = False
+    APIRouter = Any  # type: ignore
+    Request = Any  # type: ignore
+    Response = Any  # type: ignore
+    JSONResponse = Any  # type: ignore
+
+
+def _ensure_fastapi():
+    if not FASTAPI_AVAILABLE:
+        raise ImportError("FastAPI is not installed. Install it via 'pip install fastapi'.")
+
+
+async def _run_callback(cb: Optional[Callable], *args):
+    if not cb:
+        return
+    if inspect.iscoroutinefunction(cb):
+        await cb(*args)
+    else:
+        cb(*args)
+
+
+def payme_router(
+    on_success: Optional[Callable[[str, float], Any]] = None,
+    check_order: Optional[Callable[[str, float], bool]] = None,
+    secret_key: Optional[str] = None,
+    path: str = "/payme",
+) -> APIRouter:
+    """Creates a ready-to-mount FastAPI APIRouter for Payme JSON-RPC webhook."""
+    _ensure_fastapi()
+    router = APIRouter()
+
+    async def _on_success_wrapper(order_id: str, amount: float):
+        await _run_callback(on_success, order_id, amount)
+
+    handler = PaymeHandler(
+        secret_key=secret_key,
+        on_success=_on_success_wrapper,
+        check_order=check_order,
+    )
+
+    @router.post(path)
+    async def handle_payme(request: Request):
+        headers = dict(request.headers)
+        body = await request.body()
+        result = handler.process(headers, body)
+        return JSONResponse(content=result.response_data or {})
+
+    return router
+
+
+def click_router(
+    on_success: Optional[Callable[[str, float], Any]] = None,
+    check_order: Optional[Callable[[str, float], bool]] = None,
+    service_id: Optional[str] = None,
+    secret_key: Optional[str] = None,
+    path: str = "/click",
+) -> APIRouter:
+    """Creates a ready-to-mount FastAPI APIRouter for Click webhook."""
+    _ensure_fastapi()
+    router = APIRouter()
+
+    async def _on_success_wrapper(order_id: str, amount: float):
+        await _run_callback(on_success, order_id, amount)
+
+    handler = ClickHandler(
+        service_id=service_id,
+        secret_key=secret_key,
+        on_success=_on_success_wrapper,
+        check_order=check_order,
+    )
+
+    @router.post(path)
+    async def handle_click(request: Request):
+        headers = dict(request.headers)
+        body = await request.body()
+        result = handler.process(headers, body)
+        return JSONResponse(content=result.response_data or {})
+
+    return router
+
+
+def uzum_router(
+    on_success: Optional[Callable[[str, float], Any]] = None,
+    secret_key: Optional[str] = None,
+    path: str = "/uzum",
+) -> APIRouter:
+    """Creates a ready-to-mount FastAPI APIRouter for Uzum Bank webhook."""
+    _ensure_fastapi()
+    router = APIRouter()
+
+    async def _on_success_wrapper(order_id: str, amount: float):
+        await _run_callback(on_success, order_id, amount)
+
+    handler = UzumHandler(
+        secret_key=secret_key,
+        on_success=_on_success_wrapper,
+    )
+
+    @router.post(path)
+    async def handle_uzum(request: Request):
+        headers = dict(request.headers)
+        body = await request.body()
+        result = handler.process(headers, body)
+        return JSONResponse(content=result.response_data or {})
+
+    return router
+
+
+def pay_router(
+    on_success: Optional[Callable[[str, float], Any]] = None,
+    check_order: Optional[Callable[[str, float], bool]] = None,
+    prefix: str = "/payments",
+) -> APIRouter:
+    """
+    Creates an all-in-one APIRouter including Payme (/payme), Click (/click), and Uzum (/uzum).
+    Mount with `app.include_router(pay_router(...))`.
+    """
+    _ensure_fastapi()
+    master = APIRouter(prefix=prefix)
+    master.include_router(payme_router(on_success=on_success, check_order=check_order))
+    master.include_router(click_router(on_success=on_success, check_order=check_order))
+    master.include_router(uzum_router(on_success=on_success))
+    return master

pay_engine/integrations/telegram.py

@@ -0,0 +1,107 @@
+"""Telegram bot integrations for pay-engine."""
+
+from typing import Any, Dict, List, Optional, Union
+
+from ..core.config import ClickConfig, PaymeConfig, UzumConfig
+from ..providers.click.client import ClickClient
+from ..providers.payme.client import PaymeClient
+from ..providers.uzum.client import UzumClient
+
+try:
+    from aiogram.types import InlineKeyboardButton, InlineKeyboardMarkup
+    AIOGRAM_AVAILABLE = True
+except ImportError:
+    AIOGRAM_AVAILABLE = False
+    InlineKeyboardButton = Any  # type: ignore
+    InlineKeyboardMarkup = Any  # type: ignore
+
+
+def format_amount(amount: float) -> str:
+    """Format amount with space separator, e.g. 100000 -> '100 000'."""
+    if amount.is_integer():
+        return f"{int(amount):,}".replace(",", " ")
+    return f"{amount:,.2f}".replace(",", " ")
+
+
+def get_payment_links(
+    amount: float,
+    order_id: Union[str, int],
+    providers: Optional[List[str]] = None,
+    return_url: Optional[str] = None,
+) -> Dict[str, str]:
+    """
+    Generate payment URLs for multiple providers at once.
+    Only providers with valid credentials in env or config will be included.
+    """
+    if providers is None:
+        providers = ["payme", "click", "uzum"]
+
+    links = {}
+
+    if "payme" in providers:
+        cfg = PaymeConfig()
+        if cfg.merchant_id:
+            try:
+                links["payme"] = PaymeClient(merchant_id=cfg.merchant_id).create_link(
+                    amount=amount, order_id=order_id, return_url=return_url
+                )
+            except Exception:
+                pass
+
+    if "click" in providers:
+        cfg = ClickConfig()
+        if cfg.service_id and cfg.merchant_id:
+            try:
+                links["click"] = ClickClient(
+                    service_id=cfg.service_id, merchant_id=cfg.merchant_id
+                ).create_link(amount=amount, order_id=order_id, return_url=return_url)
+            except Exception:
+                pass
+
+    if "uzum" in providers:
+        cfg = UzumConfig()
+        if cfg.shop_id:
+            try:
+                links["uzum"] = UzumClient(shop_id=cfg.shop_id).create_link(
+                    amount=amount, order_id=order_id, return_url=return_url
+                )
+            except Exception:
+                pass
+
+    return links
+
+
+def payment_buttons(
+    amount: float,
+    order_id: Union[str, int],
+    providers: Optional[List[str]] = None,
+    return_url: Optional[str] = None,
+    custom_labels: Optional[Dict[str, str]] = None,
+) -> Any:
+    """
+    Generate Telegram inline keyboard with payment buttons.
+    Returns aiogram `InlineKeyboardMarkup` if aiogram is installed,
+    otherwise returns a dict representation suitable for any bot framework.
+    """
+    links = get_payment_links(amount=amount, order_id=order_id, providers=providers, return_url=return_url)
+    amount_str = format_amount(amount)
+
+    default_labels = {
+        "payme": f"💳 Payme ({amount_str} so'm)",
+        "click": f"🔹 Click ({amount_str} so'm)",
+        "uzum": f"🍇 Uzum Bank ({amount_str} so'm)",
+    }
+    labels = {**default_labels, **(custom_labels or {})}
+
+    if AIOGRAM_AVAILABLE:
+        keyboard = []
+        for prov, url in links.items():
+            btn = InlineKeyboardButton(text=labels.get(prov, prov.title()), url=url)
+            keyboard.append([btn])
+        return InlineKeyboardMarkup(inline_keyboard=keyboard)
+
+    # Fallback to standard dict format
+    raw_keyboard = []
+    for prov, url in links.items():
+        raw_keyboard.append([{"text": labels.get(prov, prov.title()), "url": url}])
+    return {"inline_keyboard": raw_keyboard}

pay_engine/providers/__init__.py

@@ -0,0 +1,16 @@
+"""Providers package for pay-engine."""
+
+from .base import BaseProvider
+from .click import ClickClient, ClickHandler
+from .payme import PaymeClient, PaymeHandler
+from .uzum import UzumClient, UzumHandler
+
+__all__ = [
+    "BaseProvider",
+    "PaymeClient",
+    "PaymeHandler",
+    "ClickClient",
+    "ClickHandler",
+    "UzumClient",
+    "UzumHandler",
+]

pay_engine/providers/base.py

@@ -0,0 +1,40 @@
+"""Abstract Base Provider for pay-engine."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, Union
+
+from ..core.models import CardChargeResult, WebhookResult
+
+
+class BaseProvider(ABC):
+    """Base class for all payment providers."""
+
+    @abstractmethod
+    def create_link(
+        self,
+        amount: float,
+        order_id: Union[str, int],
+        return_url: Optional[str] = None,
+        **kwargs: Any,
+    ) -> str:
+        """Generate a direct payment checkout URL for customer."""
+        pass
+
+    @abstractmethod
+    def verify_webhook(
+        self,
+        headers: Dict[str, str],
+        body: Union[Dict[str, Any], bytes, str],
+    ) -> WebhookResult:
+        """Verify incoming webhook request and return parsed result."""
+        pass
+
+    def charge_card(
+        self,
+        card_token: str,
+        amount: float,
+        order_id: Union[str, int],
+        **kwargs: Any,
+    ) -> CardChargeResult:
+        """Execute automated payment from saved card token. Override in providers supporting it."""
+        raise NotImplementedError(f"{self.__class__.__name__} does not support direct card charging.")

pay_engine/providers/click/__init__.py

@@ -0,0 +1,6 @@
+"""Click provider package."""
+
+from .client import ClickClient
+from .handler import ClickHandler
+
+__all__ = ["ClickClient", "ClickHandler"]