epoint-python-sdk 0.2.0__py3-none-any.whl

epoint_sdk/config.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+from urllib.parse import quote, urlsplit
+
+from goodconf import Field, GoodConf, GoodConfConfigDict
+from pydantic import BaseModel, SecretStr, field_validator
+
+from ._version import __version__
+from .enums import Currency, Language
+from .errors import ConfigurationError
+from .messages import text
+
+LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+
+class Endpoints(BaseModel):
+    payment: str = "/api/1/request"
+    checkout: str = "/api/1/checkout"
+    status: str = "/api/1/get-status"
+    reverse: str = "/api/1/reverse"
+    hold: str = "/api/1/pre-auth-request"
+    capture: str = "/api/1/pre-auth-complete"
+    card_register: str = "/api/1/card-registration"
+    card_register_pay: str = "/api/1/card-registration-with-pay"
+    card_charge: str = "/api/1/execute-pay"
+    card_status: str = "/api/1/get-status-card"
+    payout: str = "/api/1/refund-request"
+    split_payment: str = "/api/1/split-request"
+    split_charge: str = "/api/1/split-execute-pay"
+    split_register_pay: str = "/api/1/split-card-registration-with-pay"
+    installment_plans: str = "/api/1/get-installment-request"
+    installment_payment: str = "/api/1/installment-request"
+    wallets: str = "/api/1/wallet/status"
+    wallet_payment: str = "/api/1/wallet/payment"
+    widget: str = "/api/1/token/widget"
+    widget_split: str = "/api/1/token/split-payment"
+    invoice_create: str = "/api/1/invoices/create"
+    invoice_update: str = "/api/1/invoices/update"
+    invoice_view: str = "/api/1/invoices/view"
+    invoice_list: str = "/api/1/invoices/list"
+    invoice_sms: str = "/api/1/invoices/send-sms"
+    invoice_email: str = "/api/1/invoices/send-email"
+    b2b_transfer: str = "/api/1/b2b/payment"
+    b2b_status: str = "/api/1/b2b/payment/{order_id}"
+    heartbeat: str = "/api/heartbeat"
+
+
+class Settings(GoodConf):
+    model_config = GoodConfConfigDict(
+        env_prefix="EPOINT_",
+        file_env_var="EPOINT_CONFIG",
+        default_files=["epoint.toml", "epoint.yaml", "epoint.yml", "epoint.json"],
+        extra="ignore",
+        env_nested_delimiter="__",
+    )
+
+    public_key: str = Field(default="", description=text("settings.public_key"))
+    private_key: SecretStr = Field(default=SecretStr(""), description=text("settings.private_key"))
+    base_url: str = Field(default="https://epoint.az", description=text("settings.base_url"))
+    endpoints: Endpoints = Field(default_factory=Endpoints, description=text("settings.endpoints"))
+    language: Language = Field(default=Language.AZ, description=text("settings.language"))
+    currency: Currency = Field(default=Currency.AZN, description=text("settings.currency"))
+    success_url: Optional[str] = Field(default=None, description=text("settings.success_url"))
+    error_url: Optional[str] = Field(default=None, description=text("settings.error_url"))
+    timeout: float = Field(default=30.0, gt=0, description=text("settings.timeout"))
+    connect_timeout: float = Field(default=10.0, gt=0, description=text("settings.connect_timeout"))
+    max_retries: int = Field(default=2, ge=0, le=10, description=text("settings.max_retries"))
+    backoff_base: float = Field(default=0.5, ge=0, description=text("settings.backoff_base"))
+    backoff_cap: float = Field(default=8.0, ge=0, description=text("settings.backoff_cap"))
+    user_agent: str = Field(default="epoint-python-sdk/{version}", description=text("settings.user_agent"))
+    allow_insecure_http: bool = Field(default=False, description=text("settings.allow_insecure_http"))
+
+    @field_validator("base_url")
+    @classmethod
+    def _base_url(cls, value: str) -> str:
+        parts = urlsplit(value.strip())
+        if parts.scheme not in ("http", "https") or not parts.hostname:
+            raise ValueError(text("error.base_url", url=value))
+        return value.strip()
+
+    def check_transport(self) -> None:
+        parts = urlsplit(self.base_url)
+        if parts.scheme == "https" or self.allow_insecure_http or parts.hostname in LOCAL_HOSTS:
+            return
+        raise ConfigurationError(text("error.insecure", url=self.base_url))
+
+    def url(self, endpoint: str, **params: Any) -> str:
+        template = endpoint if endpoint.startswith("/") else getattr(self.endpoints, endpoint)
+        path = template.format(**{k: quote(str(v), safe="") for k, v in params.items()})
+        return self.base_url.rstrip("/") + path
+
+    def resolved_user_agent(self) -> str:
+        return self.user_agent.replace("{version}", __version__)
+
+    def keys(self) -> tuple[str, str]:
+        public, private = self.public_key.strip(), self.private_key.get_secret_value().strip()
+        if not public or not private:
+            raise ConfigurationError(text("error.missing_keys"))
+        return public, private
+
+
+Settings.__doc__ = text("settings.description")
+
+
+def load_settings(config_file: Optional[str] = None, **overrides: Any) -> Settings:
+    given = {key: value for key, value in overrides.items() if value is not None}
+    return Settings(load=True, config_file=config_file, **given)

epoint_sdk/enums.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class _Str(str, Enum):
+    def __str__(self) -> str:
+        return str(self.value)
+
+
+class Status(_Str):
+    NEW = "new"
+    SUCCESS = "success"
+    FAILED = "failed"
+    ERROR = "error"
+    RETURNED = "returned"
+    SERVER_ERROR = "server_error"
+    UNKNOWN = "unknown"
+
+    @classmethod
+    def of(cls, value: object) -> Status:
+        try:
+            return cls(str(value or "").strip().lower())
+        except ValueError:
+            return cls.UNKNOWN
+
+
+class CardStatus(_Str):
+    NEW = "new"
+    ACTIVE = "active"
+    PENDING = "pending"
+    REJECTED = "rejected"
+    EXPIRED = "expired"
+    SESSION_EXPIRED = "session_expired"
+    UNKNOWN = "unknown"
+
+    @classmethod
+    def of(cls, value: object) -> CardStatus:
+        try:
+            return cls(str(value or "").strip().lower())
+        except ValueError:
+            return cls.UNKNOWN
+
+
+class OperationCode(_Str):
+    CARD_REGISTRATION = "001"
+    PAYMENT = "100"
+    REGISTRATION_WITH_PAYMENT = "200"
+
+
+class Language(_Str):
+    AZ = "az"
+    EN = "en"
+    RU = "ru"
+
+
+class Currency(_Str):
+    AZN = "AZN"
+    USD = "USD"
+    EUR = "EUR"
+    RUB = "RUB"

epoint_sdk/errors.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class EpointError(Exception):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class ConfigurationError(EpointError):
+    pass
+
+
+class InvalidRequestError(EpointError, ValueError):
+    pass
+
+
+class SignatureError(EpointError):
+    pass
+
+
+class TransportError(EpointError):
+    def __init__(self, message: str, *, path: str = "", order_id: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.path = path
+        self.order_id = order_id
+
+
+class NotSentError(TransportError):
+    pass
+
+
+class OutcomeUnknownError(TransportError):
+    def __init__(self, message: str, *, status_code: Optional[int] = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.status_code = status_code
+
+
+class HTTPStatusError(EpointError):
+    def __init__(self, message: str, *, status_code: int, body: Any = None, path: str = "") -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+        self.path = path
+
+
+class GatewayError(EpointError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: Optional[str] = None,
+        trace_id: Optional[str] = None,
+        status_code: int = 200,
+        payload: Optional[dict[str, Any]] = None,
+        path: str = "",
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.trace_id = trace_id
+        self.status_code = status_code
+        self.payload = payload or {}
+        self.path = path
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.code:
+            parts.insert(0, f"[{self.code}]")
+        if self.trace_id:
+            parts.append(f"(trace {self.trace_id})")
+        return " ".join(parts)

epoint_sdk/messages.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from importlib import resources
+from pathlib import Path
+from typing import Any, Union
+
+import yaml
+
+PathLike = Union[str, Path]
+
+_PACKAGE_FILE = "messages.yaml"
+_catalog: dict[str, str] = {}
+
+
+def _flatten(node: Mapping[str, Any], prefix: str = "") -> dict[str, str]:
+    flat: dict[str, str] = {}
+    for key, value in node.items():
+        path = f"{prefix}{key}"
+        if isinstance(value, Mapping):
+            flat.update(_flatten(value, f"{path}."))
+        else:
+            flat[path] = str(value)
+    return flat
+
+
+def _parse(raw: str) -> dict[str, str]:
+    data = yaml.safe_load(raw) or {}
+    if not isinstance(data, Mapping):
+        raise ValueError("messages file must contain a mapping")
+    return _flatten(data)
+
+
+def _read_packaged() -> dict[str, str]:
+    raw = resources.files(__package__).joinpath(_PACKAGE_FILE).read_text(encoding="utf-8")
+    return _parse(raw)
+
+
+def catalog() -> Mapping[str, str]:
+    if not _catalog:
+        _catalog.update(_read_packaged())
+    return _catalog
+
+
+def use(source: PathLike | Mapping[str, Any]) -> None:
+    overrides = _flatten(source) if isinstance(source, Mapping) else _parse(Path(source).read_text(encoding="utf-8"))
+    unknown = set(overrides) - set(_read_packaged())
+    if unknown:
+        raise KeyError(", ".join(sorted(unknown)))
+    catalog()
+    _catalog.update(overrides)
+
+
+def reset() -> None:
+    _catalog.clear()
+
+
+def text(key: str, **params: Any) -> str:
+    template = catalog()[key]
+    return template.format(**params) if params else template

epoint_sdk/messages.yaml

@@ -0,0 +1,43 @@
+settings:
+  description: Settings for the Epoint client. Values come from code, EPOINT_* environment variables or a config file.
+  public_key: Merchant public key, for example i000000001
+  private_key: Merchant private key used to sign requests and verify callbacks
+  base_url: Gateway address
+  endpoints: Path of every API call, relative to base_url
+  language: Default language of the hosted payment page (az, en, ru)
+  currency: Default currency
+  success_url: Default page the customer returns to after a successful payment
+  error_url: Default page the customer returns to after a failed payment
+  timeout: Seconds to wait for an answer
+  connect_timeout: Seconds to wait for a connection
+  max_retries: Extra attempts for calls that are safe to repeat
+  backoff_base: First wait between retries, in seconds
+  backoff_cap: Longest wait between retries, in seconds
+  user_agent: User-Agent header
+  allow_insecure_http: Allow a plain http base_url outside localhost, for a sandbox on a private network only
+
+value:
+  amount_type: "{field} must be a number, got {value!r}"
+  amount_positive: "{field} must be greater than zero, got {value}"
+  amount_scale: "{field} {value} has more than two decimal places"
+  amount_finite: "{field} must be a finite number, got {value}"
+  empty: "{field} cannot be empty"
+  too_long: "{field} is longer than {limit} characters"
+  months: "months must be a positive whole number, got {value!r}"
+  split_amount: "split_amount {split} cannot exceed amount {amount}"
+
+error:
+  missing_keys: Epoint public_key and private_key are required
+  insecure: "Refusing to send signed requests over plain http to {url}. Use https, or set allow_insecure_http for a sandbox."
+  base_url: "base_url must be an http or https address, got {url}"
+  too_large: "The data field is larger than {limit} bytes"
+  signature: The signature does not match the data
+  data: The data field is not base64 encoded JSON
+  data_object: The data field does not decode to a JSON object
+  callback_fields: A callback needs both data and signature
+  connect: "Could not reach Epoint, nothing was sent: {error}"
+  timeout: "Epoint did not answer in time: {error}"
+  unknown_outcome: "The request reached Epoint but no answer came back ({reason}). Check the order before trying again."
+  status: "Epoint answered HTTP {status}"
+  body: "Epoint sent a body that is not JSON: {body}"
+  refused: Epoint refused the request

epoint_sdk/models.py

@@ -0,0 +1,278 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from decimal import Decimal
+from typing import Any, Mapping, Optional
+from urllib.parse import urlsplit
+
+from .enums import CardStatus, Status
+from .money import parse
+
+
+def _str(body: Mapping[str, Any], key: str) -> Optional[str]:
+    value = body.get(key)
+    if value is None or value == "":
+        return None
+    return str(value)
+
+
+@dataclass(frozen=True)
+class Redirect:
+    redirect_url: Optional[str]
+    transaction: Optional[str]
+    trace_id: Optional[str] = None
+    message: Optional[str] = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> Redirect:
+        return cls(_str(body, "redirect_url"), _str(body, "transaction"), _str(body, "trace_id"), _str(body, "message"),
+                   dict(body))
+
+
+@dataclass(frozen=True)
+class Transaction:
+    status: Status
+    transaction: Optional[str] = None
+    order_id: Optional[str] = None
+    amount: Optional[Decimal] = None
+    code: Optional[str] = None
+    message: Optional[str] = None
+    bank_transaction: Optional[str] = None
+    bank_response: Optional[str] = None
+    operation_code: Optional[str] = None
+    rrn: Optional[str] = None
+    card_id: Optional[str] = None
+    card_name: Optional[str] = None
+    card_mask: Optional[str] = None
+    split_amount: Optional[Decimal] = None
+    other_attr: Any = None
+    trace_id: Optional[str] = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> Transaction:
+        return cls(
+            status=Status.of(body.get("status")),
+            transaction=_str(body, "transaction"),
+            order_id=_str(body, "order_id"),
+            amount=parse(body.get("amount")),
+            code=_str(body, "code"),
+            message=_str(body, "message"),
+            bank_transaction=_str(body, "bank_transaction"),
+            bank_response=_str(body, "bank_response"),
+            operation_code=_str(body, "operation_code"),
+            rrn=_str(body, "rrn"),
+            card_id=_str(body, "card_id"),
+            card_name=_str(body, "card_name"),
+            card_mask=_str(body, "card_mask"),
+            split_amount=parse(body.get("split_amount")),
+            other_attr=body.get("other_attr"),
+            trace_id=_str(body, "trace_id"),
+            raw=dict(body),
+        )
+
+    @property
+    def paid(self) -> bool:
+        return self.status is Status.SUCCESS
+
+    @property
+    def returned(self) -> bool:
+        return self.status is Status.RETURNED
+
+    @property
+    def failed(self) -> bool:
+        return self.status in (Status.FAILED, Status.ERROR)
+
+    @property
+    def pending(self) -> bool:
+        return self.status in (Status.NEW, Status.SERVER_ERROR, Status.UNKNOWN)
+
+    @property
+    def final(self) -> bool:
+        return not self.pending
+
+    def matches(self, *, order_id: Optional[str] = None, amount: Any = None, transaction: Optional[str] = None) -> bool:
+        if order_id is not None and self.order_id != str(order_id):
+            return False
+        if transaction is not None and self.transaction is not None and self.transaction != str(transaction):
+            return False
+        if amount is not None and self.amount != parse(amount):
+            return False
+        return True
+
+
+Callback = Transaction
+
+
+@dataclass(frozen=True)
+class Result:
+    status: Status
+    transaction: Optional[str] = None
+    message: Optional[str] = None
+    trace_id: Optional[str] = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> Result:
+        return cls(Status.of(body.get("status")), _str(body, "transaction"), _str(body, "message"),
+                   _str(body, "trace_id"), dict(body))
+
+    @property
+    def ok(self) -> bool:
+        return self.status is Status.SUCCESS
+
+
+@dataclass(frozen=True)
+class CardRegistration:
+    card_id: Optional[str]
+    redirect_url: Optional[str]
+    transaction: Optional[str] = None
+    trace_id: Optional[str] = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> CardRegistration:
+        return cls(_str(body, "card_id"), _str(body, "redirect_url"), _str(body, "transaction"), _str(body, "trace_id"),
+                   dict(body))
+
+
+@dataclass(frozen=True)
+class Card:
+    id: Optional[str]
+    status: CardStatus
+    name: Optional[str] = None
+    mask: Optional[str] = None
+    expiry: Optional[str] = None
+    description: Optional[str] = None
+    trace_id: Optional[str] = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> Card:
+        return cls(_str(body, "id") or _str(body, "card_id"), CardStatus.of(body.get("status")), _str(body, "name"),
+                   _str(body, "mask"), _str(body, "expired_date"), _str(body, "description"), _str(body, "trace_id"),
+                   dict(body))
+
+    @property
+    def usable(self) -> bool:
+        return self.status is CardStatus.ACTIVE
+
+
+@dataclass(frozen=True)
+class Widget:
+    widget_url: Optional[str]
+    transaction: Optional[str] = None
+    trace_id: Optional[str] = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> Widget:
+        return cls(_str(body, "widget_url"), _str(body, "transaction"), _str(body, "trace_id"), dict(body))
+
+    @property
+    def origin(self) -> Optional[str]:
+        return origin_of(self.widget_url)
+
+
+def origin_of(url: Optional[str]) -> Optional[str]:
+    if not url:
+        return None
+    parts = urlsplit(url)
+    if not parts.scheme or not parts.netloc:
+        return None
+    return f"{parts.scheme}://{parts.netloc}".lower()
+
+
+@dataclass(frozen=True)
+class WidgetMessage:
+    status: Status
+    order_id: Optional[str] = None
+    transaction: Optional[str] = None
+    amount: Optional[Decimal] = None
+    card_mask: Optional[str] = None
+    message: Optional[str] = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_event(cls, data: Mapping[str, Any]) -> WidgetMessage:
+        found = data.get("payment")
+        payment: Mapping[str, Any] = found if isinstance(found, Mapping) else {}
+        status = payment.get("status") or data.get("status")
+        return cls(Status.of(status), _str(payment, "order_id"), _str(payment, "transaction"),
+                   parse(payment.get("amount")), _str(payment, "card_mask"), _str(payment, "message"), dict(data))
+
+    @property
+    def looks_paid(self) -> bool:
+        return self.status is Status.SUCCESS
+
+
+@dataclass(frozen=True)
+class InstallmentPlan:
+    card_id: str
+    name: str
+    months: tuple[int, ...]
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> InstallmentPlan:
+        months = body.get("installment_months") or []
+        return cls(str(body.get("installment_card_id") or ""), str(body.get("name") or ""),
+                   tuple(int(m) for m in months if str(m).isdigit()))
+
+
+@dataclass(frozen=True)
+class Wallet:
+    id: str
+    name: str
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> Wallet:
+        return cls(str(body.get("id") or body.get("wallet_id") or ""), str(body.get("name") or ""))
+
+
+@dataclass(frozen=True)
+class Invoice:
+    id: Optional[int]
+    amount: Optional[Decimal]
+    status: Optional[str]
+    name: Optional[str] = None
+    description: Optional[str] = None
+    phone: Optional[str] = None
+    email: Optional[str] = None
+    period_from: Optional[str] = None
+    period_to: Optional[str] = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> Invoice:
+        ident = str(body.get("id") or "")
+        return cls(int(ident) if ident.isdigit() else None, parse(body.get("sum")), _str(body, "status"),
+                   _str(body, "name"), _str(body, "description"), _str(body, "phone"), _str(body, "email"),
+                   _str(body, "period_from"), _str(body, "period_to"), dict(body))
+
+
+@dataclass(frozen=True)
+class Transfer:
+    order_id: Optional[str]
+    status: Optional[str]
+    bulk_id: Optional[str] = None
+    amount: Optional[Decimal] = None
+    payee_iban: Optional[str] = None
+    payee_name: Optional[str] = None
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_api(cls, body: Mapping[str, Any]) -> Transfer:
+        return cls(_str(body, "order_id"), _str(body, "status"), _str(body, "bulkId") or _str(body, "bulk_id"),
+                   parse(body.get("amount")), _str(body, "payee_iban"), _str(body, "payee_name"), dict(body))
+
+
+@dataclass(frozen=True)
+class CheckoutForm:
+    action: str
+    data: str
+    signature: str
+
+    @property
+    def fields(self) -> dict[str, str]:
+        return {"data": self.data, "signature": self.signature}

epoint_sdk/money.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from decimal import Decimal, InvalidOperation
+from typing import Union
+
+from .errors import InvalidRequestError
+from .messages import text
+
+Amount = Union[Decimal, int, float, str]
+CENT = Decimal("0.01")
+
+
+def amount(value: Amount, field: str = "amount") -> Decimal:
+    if isinstance(value, bool) or not isinstance(value, (Decimal, int, float, str)):
+        raise InvalidRequestError(text("value.amount_type", field=field, value=value))
+    try:
+        number = Decimal(str(value).strip()) if not isinstance(value, Decimal) else value
+    except InvalidOperation:
+        raise InvalidRequestError(text("value.amount_type", field=field, value=value)) from None
+    if not number.is_finite():
+        raise InvalidRequestError(text("value.amount_finite", field=field, value=value))
+    if number <= 0:
+        raise InvalidRequestError(text("value.amount_positive", field=field, value=value))
+    if number != number.quantize(CENT):
+        raise InvalidRequestError(text("value.amount_scale", field=field, value=value))
+    return number.quantize(CENT)
+
+
+def wire(value: Decimal) -> float:
+    return float(value)
+
+
+def parse(value: object) -> Decimal | None:
+    if value is None or value == "" or isinstance(value, bool):
+        return None
+    try:
+        number = Decimal(str(value))
+    except InvalidOperation:
+        return None
+    return number.quantize(CENT) if number.is_finite() else None