eupago 0.5.0__py3-none-any.whl

eupago/__init__.py

@@ -0,0 +1,41 @@
+"""Unofficial Python SDK for the eupago payment gateway."""
+
+from eupago._client import EupagoClient
+from eupago.exceptions import (
+    ApiError,
+    AuthenticationError,
+    DecryptionError,
+    EupagoError,
+    NetworkError,
+    NotFoundError,
+    PaymentError,
+    RateLimitError,
+    ServiceUnavailableError,
+    SignatureError,
+    ValidationError,
+    WebhookError,
+)
+from eupago.models import Customer, PaymentResult, PaymentStatus, WebhookEvent
+
+__version__ = "0.5.0"
+
+__all__ = [
+    "ApiError",
+    "AuthenticationError",
+    "Customer",
+    "DecryptionError",
+    "EupagoClient",
+    "EupagoError",
+    "NetworkError",
+    "NotFoundError",
+    "PaymentError",
+    "PaymentResult",
+    "PaymentStatus",
+    "RateLimitError",
+    "ServiceUnavailableError",
+    "SignatureError",
+    "ValidationError",
+    "WebhookError",
+    "WebhookEvent",
+    "__version__",
+]

eupago/_auth.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from eupago._http import HttpTransport
+
+
+class ApiKeyAuth:
+    def __init__(self, api_key: str) -> None:
+        self.api_key = api_key
+
+    def apply_header(self, headers: dict[str, str]) -> dict[str, str]:
+        return {**headers, "Authorization": f"ApiKey {self.api_key}"}
+
+    def apply_body(self, body: dict[str, Any]) -> dict[str, Any]:
+        return {**body, "chave": self.api_key}
+
+
+class StaticBearerAuth:
+    """Bearer token supplied directly by the caller (no token fetch).
+
+    Use this when the caller has already obtained a Bearer through some other
+    flow (e.g. the eupago backoffice login). It exposes the same
+    ``apply_header`` / ``apply_header_async`` surface as :class:`OAuthAuth`
+    so the rest of the SDK can treat them interchangeably.
+    """
+
+    def __init__(self, token: str) -> None:
+        self._token = token
+
+    def get_token(self) -> str:
+        return self._token
+
+    async def get_token_async(self) -> str:
+        return self._token
+
+    def apply_header(self, headers: dict[str, str]) -> dict[str, str]:
+        return {**headers, "Authorization": f"Bearer {self._token}"}
+
+    async def apply_header_async(self, headers: dict[str, str]) -> dict[str, str]:
+        return {**headers, "Authorization": f"Bearer {self._token}"}
+
+
+class OAuthAuth:
+    _TOKEN_BUFFER_SECONDS = 60
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        transport: HttpTransport,
+        auth_path: str = "/api/auth/token",
+    ) -> None:
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._transport = transport
+        self._auth_path = auth_path
+        self._token: str | None = None
+        self._expires_at: float = 0.0
+
+    def _is_expired(self) -> bool:
+        return time.monotonic() >= self._expires_at
+
+    def _fetch_token(self) -> str:
+        response = self._transport.request(
+            "POST",
+            self._auth_path,
+            json={
+                "client_id": self._client_id,
+                "client_secret": self._client_secret,
+                "grant_type": "client_credentials",
+            },
+        )
+        data = response.json()
+        self._token = data["access_token"]
+        expires_in: int = data.get("expires_in", 3600)
+        self._expires_at = time.monotonic() + expires_in - self._TOKEN_BUFFER_SECONDS
+        return self._token
+
+    async def _fetch_token_async(self) -> str:
+        response = await self._transport.request_async(
+            "POST",
+            self._auth_path,
+            json={
+                "client_id": self._client_id,
+                "client_secret": self._client_secret,
+                "grant_type": "client_credentials",
+            },
+        )
+        data = response.json()
+        self._token = data["access_token"]
+        expires_in: int = data.get("expires_in", 3600)
+        self._expires_at = time.monotonic() + expires_in - self._TOKEN_BUFFER_SECONDS
+        return self._token
+
+    def get_token(self) -> str:
+        if self._token is None or self._is_expired():
+            return self._fetch_token()
+        return self._token
+
+    async def get_token_async(self) -> str:
+        if self._token is None or self._is_expired():
+            return await self._fetch_token_async()
+        return self._token
+
+    def apply_header(self, headers: dict[str, str]) -> dict[str, str]:
+        return {**headers, "Authorization": f"Bearer {self.get_token()}"}
+
+    async def apply_header_async(self, headers: dict[str, str]) -> dict[str, str]:
+        token = await self.get_token_async()
+        return {**headers, "Authorization": f"Bearer {token}"}

eupago/_client.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from typing import Any
+
+from eupago._auth import ApiKeyAuth, OAuthAuth, StaticBearerAuth
+from eupago._config import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    PRODUCTION_BASE_URL,
+    SANDBOX_BASE_URL,
+)
+from eupago._http import AuditHook, HttpTransport
+from eupago.services.apple_pay import ApplePayService
+from eupago.services.credit_card import CreditCardService
+from eupago.services.google_pay import GooglePayService
+from eupago.services.mbway import MBWayService
+from eupago.services.multibanco import MultibancoService
+from eupago.services.pay_by_link import PayByLinkService
+from eupago.services.refund import RefundService
+from eupago.webhooks import Webhooks
+
+
+class EupagoClient:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        management_bearer: str | None = None,
+        webhook_secret: str | None = None,
+        sandbox: bool = False,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        """
+        :param management_bearer: pre-obtained Bearer token for ``/api/management/*``.
+            Overrides ``client_id``/``client_secret`` when set. Intended for tests
+            or one-off scripts where the caller already has a token (e.g. from the
+            backoffice login flow); production callers should prefer OAuth via
+            ``client_id``/``client_secret``.
+        """
+        from eupago import __version__
+
+        base_url = SANDBOX_BASE_URL if sandbox else PRODUCTION_BASE_URL
+
+        self._transport = HttpTransport(
+            base_url=base_url,
+            version=__version__,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._auth = ApiKeyAuth(api_key)
+        self._oauth: OAuthAuth | StaticBearerAuth | None = None
+
+        if management_bearer:
+            self._oauth = StaticBearerAuth(management_bearer)
+        elif client_id and client_secret:
+            self._oauth = OAuthAuth(client_id, client_secret, self._transport)
+
+        self._services: dict[str, Any] = {}
+        self._webhooks = Webhooks(webhook_secret)
+
+    def _get_service(self, name: str, cls: type[Any]) -> Any:
+        if name not in self._services:
+            self._services[name] = cls(self._transport, self._auth, self._oauth)
+        return self._services[name]
+
+    @property
+    def mbway(self) -> MBWayService:
+        return self._get_service("mbway", MBWayService)  # type: ignore[no-any-return]
+
+    @property
+    def multibanco(self) -> MultibancoService:
+        return self._get_service("multibanco", MultibancoService)  # type: ignore[no-any-return]
+
+    @property
+    def credit_card(self) -> CreditCardService:
+        return self._get_service("credit_card", CreditCardService)  # type: ignore[no-any-return]
+
+    @property
+    def apple_pay(self) -> ApplePayService:
+        return self._get_service("apple_pay", ApplePayService)  # type: ignore[no-any-return]
+
+    @property
+    def google_pay(self) -> GooglePayService:
+        return self._get_service("google_pay", GooglePayService)  # type: ignore[no-any-return]
+
+    @property
+    def pay_by_link(self) -> PayByLinkService:
+        return self._get_service("pay_by_link", PayByLinkService)  # type: ignore[no-any-return]
+
+    @property
+    def refunds(self) -> RefundService:
+        return self._get_service("refunds", RefundService)  # type: ignore[no-any-return]
+
+    @property
+    def webhooks(self) -> Webhooks:
+        return self._webhooks
+
+    def set_audit_hook(self, hook: AuditHook | None) -> None:
+        self._transport.set_audit_hook(hook)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    def __enter__(self) -> EupagoClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    async def __aenter__(self) -> EupagoClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()

eupago/_config.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+SANDBOX_BASE_URL = "https://sandbox.eupago.pt"
+PRODUCTION_BASE_URL = "https://clientes.eupago.pt"
+
+API_PREFIX = "/api/v1.02"
+LEGACY_PREFIX = "/clientes/rest_api"
+AUTH_PREFIX = "/api/auth"
+MANAGEMENT_PREFIX = "/api/management/v1.02"
+
+DEFAULT_TIMEOUT = 10.0
+DEFAULT_MAX_RETRIES = 3
+MAX_RETRY_DELAY = 5.0
+INITIAL_RETRY_DELAY = 0.5

eupago/_http.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+import asyncio
+import platform
+import random
+import time
+from typing import Any, Callable
+
+import httpx
+
+from eupago._config import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    INITIAL_RETRY_DELAY,
+    MAX_RETRY_DELAY,
+)
+from eupago._logging import logger
+from eupago.exceptions import (
+    ApiError,
+    AuthenticationError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    ServiceUnavailableError,
+)
+
+AuditHook = Callable[[httpx.Request, httpx.Response, float], Any]
+
+
+def _user_agent(version: str) -> str:
+    return f"eupago-python/{version} (Python/{platform.python_version()})"
+
+
+class HttpTransport:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        version: str = "0.0.0",
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self._base_url = base_url
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._audit_hook: AuditHook | None = None
+        self._ua = _user_agent(version)
+
+        self._sync_client = httpx.Client(
+            base_url=base_url,
+            timeout=timeout,
+            headers={"User-Agent": self._ua, "Content-Type": "application/json"},
+        )
+        self._async_client: httpx.AsyncClient | None = None
+
+    def _get_async_client(self) -> httpx.AsyncClient:
+        if self._async_client is None or self._async_client.is_closed:
+            self._async_client = httpx.AsyncClient(
+                base_url=self._base_url,
+                timeout=self._timeout,
+                headers={"User-Agent": self._ua, "Content-Type": "application/json"},
+            )
+        return self._async_client
+
+    def set_audit_hook(self, hook: AuditHook | None) -> None:
+        self._audit_hook = hook
+
+    def _should_retry(self, method: str, response: httpx.Response | None, attempt: int) -> bool:
+        if attempt >= self._max_retries:
+            return False
+        if method.upper() != "GET":
+            return False
+        if response is None:
+            return True
+        return response.status_code >= 500
+
+    def _retry_delay(self, attempt: int) -> float:
+        delay = min(INITIAL_RETRY_DELAY * (2**attempt), MAX_RETRY_DELAY)
+        jitter: float = delay * (0.5 + random.random() * 0.5)  # noqa: S311
+        return jitter
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        if response.status_code < 400:
+            return
+
+        try:
+            data = response.json()
+        except Exception:
+            data = {}
+
+        message = str(
+            data.get("message")
+            or data.get("Message")
+            or data.get("text")
+            or data.get("resposta")
+            or response.text
+        )
+        error_code_raw = data.get("code") or data.get("estado")
+        error_code: int | str | None
+        if error_code_raw is None:
+            error_code = None
+        else:
+            try:
+                error_code = int(error_code_raw)
+            except (ValueError, TypeError):
+                error_code = error_code_raw
+
+        kwargs: dict[str, Any] = {
+            "status_code": response.status_code,
+            "error_code": error_code,
+        }
+
+        if response.status_code == 401:
+            raise AuthenticationError(message)
+        if response.status_code == 404:
+            raise NotFoundError(message, **kwargs)
+        if response.status_code == 429:
+            raise RateLimitError(message, **kwargs)
+        if response.status_code >= 500:
+            raise ServiceUnavailableError(message, **kwargs)
+        raise ApiError(message, **kwargs)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        last_exc: Exception | None = None
+        effective_headers = dict(headers or {})
+        # Form-encoded body needs the matching Content-Type (httpx Client default is JSON).
+        if data is not None:
+            effective_headers["Content-Type"] = "application/x-www-form-urlencoded"
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                start = time.monotonic()
+                response = self._sync_client.request(
+                    method,
+                    path,
+                    json=json,
+                    data=data,
+                    params=params,
+                    headers=effective_headers,
+                )
+                duration_ms = (time.monotonic() - start) * 1000
+                logger.debug(
+                    "HTTP %s %s → %d (%.0fms)", method, path, response.status_code, duration_ms
+                )
+
+                if self._audit_hook is not None:
+                    self._audit_hook(response.request, response, duration_ms)
+
+                if response.status_code >= 400:
+                    if self._should_retry(method, response, attempt):
+                        time.sleep(self._retry_delay(attempt))
+                        continue
+                    self._raise_for_status(response)
+
+                return response
+
+            except (httpx.ConnectError, httpx.TimeoutException) as exc:
+                last_exc = exc
+                logger.debug(
+                    "HTTP %s %s → %s (attempt %d)", method, path, type(exc).__name__, attempt + 1
+                )
+                if self._should_retry(method, None, attempt):
+                    time.sleep(self._retry_delay(attempt))
+                    continue
+                raise NetworkError(str(exc)) from exc
+
+        raise NetworkError(str(last_exc)) from last_exc
+
+    async def request_async(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        client = self._get_async_client()
+        last_exc: Exception | None = None
+        effective_headers = dict(headers or {})
+        if data is not None:
+            effective_headers["Content-Type"] = "application/x-www-form-urlencoded"
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                start = time.monotonic()
+                response = await client.request(
+                    method,
+                    path,
+                    json=json,
+                    data=data,
+                    params=params,
+                    headers=effective_headers,
+                )
+                duration_ms = (time.monotonic() - start) * 1000
+                logger.debug(
+                    "HTTP %s %s → %d (%.0fms)", method, path, response.status_code, duration_ms
+                )
+
+                if self._audit_hook is not None:
+                    self._audit_hook(response.request, response, duration_ms)
+
+                if response.status_code >= 400:
+                    if self._should_retry(method, response, attempt):
+                        await asyncio.sleep(self._retry_delay(attempt))
+                        continue
+                    self._raise_for_status(response)
+
+                return response
+
+            except (httpx.ConnectError, httpx.TimeoutException) as exc:
+                last_exc = exc
+                logger.debug(
+                    "HTTP %s %s → %s (attempt %d)", method, path, type(exc).__name__, attempt + 1
+                )
+                if self._should_retry(method, None, attempt):
+                    await asyncio.sleep(self._retry_delay(attempt))
+                    continue
+                raise NetworkError(str(exc)) from exc
+
+        raise NetworkError(str(last_exc)) from last_exc
+
+    def close(self) -> None:
+        self._sync_client.close()
+
+    async def aclose(self) -> None:
+        self._sync_client.close()
+        if self._async_client is not None:
+            await self._async_client.aclose()

eupago/_logging.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import logging
+import re
+
+logger = logging.getLogger("eupago")
+
+_PII_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(r"\b\d{9}\b"), "***PHONE***"),
+    (re.compile(r"\b351#\d{9}\b"), "***PHONE***"),
+    (re.compile(r"\b[+]351\s?\d{9}\b"), "***PHONE***"),
+    (re.compile(r"\b[\w.+-]+@[\w-]+\.[\w.]+\b"), "***EMAIL***"),
+    (re.compile(r"\b\d{3}[.\s]?\d{3}[.\s]?\d{3}\b"), "***NIF***"),
+]
+
+
+def redact_pii(text: str) -> str:
+    for pattern, replacement in _PII_PATTERNS:
+        text = pattern.sub(replacement, text)
+    return text
+
+
+class PiiFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        if isinstance(record.msg, str):
+            record.msg = redact_pii(record.msg)
+        return True
+
+
+logger.addFilter(PiiFilter())

eupago/exceptions.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+
+class EupagoError(Exception):
+    """Base exception for all eupago SDK errors."""
+
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super().__init__(message)
+
+
+class AuthenticationError(EupagoError):
+    """Invalid API key or expired OAuth token."""
+
+
+class ValidationError(EupagoError):
+    """Invalid parameters detected before calling the API."""
+
+
+class ApiError(EupagoError):
+    """Error response from the eupago API."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        error_code: int | str | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.error_code = error_code
+        self.request_id = request_id
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.status_code is not None:
+            parts.append(f"HTTP {self.status_code}")
+        if self.error_code is not None:
+            parts.append(f"code={self.error_code}")
+        if self.request_id:
+            parts.append(f"request_id={self.request_id}")
+        return " | ".join(parts)
+
+
+class PaymentError(ApiError):
+    """Payment failed or was declined."""
+
+
+class RateLimitError(ApiError):
+    """Request was rate limited."""
+
+
+class NotFoundError(ApiError):
+    """Reference or transaction not found."""
+
+
+class ServiceUnavailableError(ApiError):
+    """eupago API is unavailable."""
+
+
+class WebhookError(EupagoError):
+    """Webhook processing error."""
+
+
+class SignatureError(WebhookError):
+    """Invalid HMAC signature on webhook."""
+
+
+class DecryptionError(WebhookError):
+    """Failed to decrypt encrypted webhook payload."""
+
+
+class NetworkError(EupagoError):
+    """Network-level error: timeout, connection refused, DNS failure."""

eupago/models/__init__.py

@@ -0,0 +1,10 @@
+from eupago.models.customer import Customer
+from eupago.models.payment import PaymentResult, PaymentStatus
+from eupago.models.webhook import WebhookEvent
+
+__all__ = [
+    "Customer",
+    "PaymentResult",
+    "PaymentStatus",
+    "WebhookEvent",
+]

eupago/models/_base.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from pydantic import BaseModel as PydanticBaseModel
+from pydantic import ConfigDict
+
+
+class BaseModel(PydanticBaseModel):
+    model_config = ConfigDict(
+        populate_by_name=True,
+        str_strip_whitespace=True,
+    )

eupago/models/customer.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from eupago.models._base import BaseModel
+
+
+class Customer(BaseModel):
+    name: str | None = None
+    email: str | None = None
+    phone_number: str | None = None
+    notify: bool = True