python-myanmar-payments 4.0.0a1__py3-none-any.whl

python_myanmar_payments/__init__.py

@@ -0,0 +1,111 @@
+"""Python SDK for Myanmar payment gateways.
+
+KBZ Pay, Wave Money, AYA Pay, Yoma MMQR and CyberSource. Typed requests and
+results, exact amounts, sync and async clients.
+"""
+
+from ._amount import Amount, AmountInput
+from ._cache import AsyncTokenCache, MemoryTokenCache, TokenCache
+from ._callback import BodyInput, CallbackRequest, HeadersInput, QueryInput
+from ._errors import (
+    ApiError,
+    ConfigurationError,
+    InvalidPaymentDataError,
+    PaymentError,
+    SignatureVerificationError,
+)
+from ._facade import AsyncMyanmarPayments, MyanmarPayments
+from ._http import DEFAULT_TIMEOUT
+from ._results import (
+    Acknowledgement,
+    AppPayment,
+    FormField,
+    FormPayment,
+    PaymentCallback,
+    PaymentResult,
+    PaymentStatusResult,
+    QrPayment,
+    RedirectPayment,
+)
+from ._status import PaymentFlow, PaymentStatus, resolve_status
+from ._version import __version__
+from .aya_pay import (
+    AsyncAyaPay,
+    AyaPay,
+    AyaPayConfig,
+    AyaPayMethod,
+    AyaPayPaymentData,
+    AyaPayService,
+)
+from .cyber_source import (
+    CyberSource,
+    CyberSourceConfig,
+    CyberSourcePaymentData,
+    CyberSourceTransactionType,
+)
+from .kbz_pay import AsyncKbzPay, KbzPay, KbzPayConfig, KbzPayPaymentData, KbzPaySigner
+from .wave_money import (
+    AsyncWaveMoney,
+    WaveMoney,
+    WaveMoneyConfig,
+    WaveMoneyItem,
+    WaveMoneyPaymentData,
+)
+from .yoma_mmqr import AsyncYomaMmqr, YomaMmqr, YomaMmqrConfig, YomaMmqrPaymentData
+
+__all__ = [
+    "DEFAULT_TIMEOUT",
+    "Acknowledgement",
+    "Amount",
+    "AmountInput",
+    "ApiError",
+    "AppPayment",
+    "AsyncAyaPay",
+    "AsyncKbzPay",
+    "AsyncMyanmarPayments",
+    "AsyncTokenCache",
+    "AsyncWaveMoney",
+    "AsyncYomaMmqr",
+    "AyaPay",
+    "AyaPayConfig",
+    "AyaPayMethod",
+    "AyaPayPaymentData",
+    "AyaPayService",
+    "BodyInput",
+    "CallbackRequest",
+    "ConfigurationError",
+    "CyberSource",
+    "CyberSourceConfig",
+    "CyberSourcePaymentData",
+    "CyberSourceTransactionType",
+    "FormField",
+    "FormPayment",
+    "HeadersInput",
+    "InvalidPaymentDataError",
+    "KbzPay",
+    "KbzPayConfig",
+    "KbzPayPaymentData",
+    "KbzPaySigner",
+    "MemoryTokenCache",
+    "MyanmarPayments",
+    "PaymentCallback",
+    "PaymentError",
+    "PaymentFlow",
+    "PaymentResult",
+    "PaymentStatus",
+    "PaymentStatusResult",
+    "QrPayment",
+    "QueryInput",
+    "RedirectPayment",
+    "SignatureVerificationError",
+    "TokenCache",
+    "WaveMoney",
+    "WaveMoneyConfig",
+    "WaveMoneyItem",
+    "WaveMoneyPaymentData",
+    "YomaMmqr",
+    "YomaMmqrConfig",
+    "YomaMmqrPaymentData",
+    "__version__",
+    "resolve_status",
+]

python_myanmar_payments/_amount.py

@@ -0,0 +1,178 @@
+"""The exact money amount type."""
+
+from __future__ import annotations
+
+import json
+import re
+from decimal import Decimal
+
+from ._errors import InvalidPaymentDataError
+
+__all__ = ["Amount", "AmountInput"]
+
+_PATTERN = re.compile(r"[0-9]+(?:\.[0-9]+)?")
+
+
+class Amount:
+    """An exact, non-negative money amount, kept as decimal text.
+
+    It never passes through a float, so it is never rounded. Build one with
+    :meth:`Amount.kyat` for whole amounts, :meth:`Amount.parse` for decimal text or
+    :meth:`Amount.of` for any accepted input. Each gateway then checks it against
+    its documented rules (Wave Money, AYA and Yoma MMQR only accept whole kyat,
+    KBZ Pay up to 2 decimal places, CyberSource any).
+
+    Amounts are immutable and ``str(amount)`` is the exact text sent to the
+    gateway, e.g. ``"1000.50"``.
+    """
+
+    __slots__ = ("_value",)
+
+    _value: str
+
+    def __init__(self, amount: AmountInput) -> None:
+        """The same as :meth:`Amount.of`: ``Amount(1000)``, ``Amount("1000.50")``."""
+        object.__setattr__(self, "_value", Amount.of(amount)._value)
+
+    @classmethod
+    def _make(cls, value: str) -> Amount:
+        instance = object.__new__(cls)
+        object.__setattr__(instance, "_value", value)
+        return instance
+
+    def __setattr__(self, name: str, value: object) -> None:
+        raise AttributeError("Amount is immutable")
+
+    @classmethod
+    def kyat(cls, amount: int) -> Amount:
+        """A whole amount, e.g. ``Amount.kyat(1000)`` for 1000 MMK.
+
+        Works for whole units of any currency. Floats, booleans and negative
+        values raise an :class:`InvalidPaymentDataError` for the ``amount`` field.
+        """
+        if isinstance(amount, bool) or not isinstance(amount, int):
+            raise _invalid(
+                "The amount field must be a whole number of kyat; use "
+                "Amount.parse('10.50') for decimal amounts, "
+                f"got {amount!r}."
+            )
+        if amount < 0:
+            raise _invalid("The amount field must not be negative.")
+        return cls._make(str(amount))
+
+    @classmethod
+    def parse(cls, amount: str) -> Amount:
+        """A decimal amount written as plain digits, e.g. ``Amount.parse("1000.50")``.
+
+        Signs, exponents, spaces and thousands separators are rejected with an
+        :class:`InvalidPaymentDataError`. Leading zeros of the whole part are
+        removed (``"007.50"`` becomes ``"7.50"``); the fractional digits are kept
+        exactly as given.
+        """
+        if not isinstance(amount, str) or _PATTERN.fullmatch(amount) is None:
+            raise _invalid(
+                "The amount field must be a number such as 1000 or 1000.50, "
+                f"got {json.dumps(amount, ensure_ascii=False, default=repr)}."
+            )
+        whole, dot, fraction = amount.partition(".")
+        whole = whole.lstrip("0") or "0"
+        return cls._make(f"{whole}.{fraction}" if dot else whole)
+
+    @classmethod
+    def of(cls, amount: AmountInput) -> Amount:
+        """Any accepted amount input as an :class:`Amount`.
+
+        Takes an ``Amount`` (returned as is), a whole ``int`` (as
+        :meth:`kyat`), decimal text (as :meth:`parse`) or a finite, non-negative
+        :class:`~decimal.Decimal` (its exact digits, e.g. ``Decimal("1000.50")``
+        is ``"1000.50"``). Floats are never accepted.
+        """
+        if isinstance(amount, Amount):
+            return amount
+        if isinstance(amount, str):
+            return cls.parse(amount)
+        if isinstance(amount, Decimal):
+            if not amount.is_finite():
+                raise _invalid(f"The amount field must be a finite number, got {amount!r}.")
+            if amount < 0:
+                raise _invalid("The amount field must not be negative.")
+            return cls.parse(format(amount.copy_abs(), "f"))
+        return cls.kyat(amount)
+
+    def __str__(self) -> str:
+        return self._value
+
+    def __repr__(self) -> str:
+        return f"Amount('{self._value}')"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Amount):
+            return _normalize(self._value) == _normalize(other._value)
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(_normalize(self._value))
+
+    def decimal_places(self) -> int:
+        """The number of fractional digits, e.g. ``2`` for ``1000.50``."""
+        _, dot, fraction = self._value.partition(".")
+        return len(fraction) if dot else 0
+
+    def whole_part(self) -> str:
+        """The digits before the decimal point, e.g. ``"1000"`` for ``1000.50``."""
+        return self._value.partition(".")[0]
+
+    def is_zero(self) -> bool:
+        """Whether the amount equals zero, e.g. ``0`` or ``0.00``."""
+        return self._value.replace(".", "").strip("0") == ""
+
+    def is_positive(self) -> bool:
+        """Whether the amount is greater than zero."""
+        return not self.is_zero()
+
+    def to_decimal(self) -> Decimal:
+        """The amount as an exact :class:`~decimal.Decimal`, e.g. ``Decimal("1000.50")``."""
+        return Decimal(self._value)
+
+    def equals(self, other: Amount | str | None) -> bool:
+        """Whether both amounts have the same value.
+
+        Leading zeros of the whole part and trailing zeros of the fraction are
+        ignored: ``1000``, ``01000`` and ``1000.00`` are equal. Text such as
+        ``callback.amount`` must be plain digits with an optional fraction;
+        anything else, and ``None``, is never equal, so a gateway amount that was
+        not sent never matches.
+        """
+        if isinstance(other, Amount):
+            return self == other
+        if not isinstance(other, str) or _PATTERN.fullmatch(other) is None:
+            return False
+        return _normalize(self._value) == _normalize(other)
+
+
+AmountInput = Amount | int | str | Decimal
+"""What payment data accepts as an amount: an :class:`Amount`, a whole ``int``,
+decimal text such as ``"1000.50"`` or a :class:`~decimal.Decimal`. Never a float."""
+
+
+def _normalize(value: str) -> str:
+    whole, _, fraction = value.partition(".")
+    whole = whole.lstrip("0") or "0"
+    fraction = fraction.rstrip("0")
+    return f"{whole}.{fraction}" if fraction else whole
+
+
+def _invalid(message: str) -> InvalidPaymentDataError:
+    return InvalidPaymentDataError({"amount": message})
+
+
+def to_amount(value: object) -> Amount | None:
+    """``value`` as an :class:`Amount`, or ``None`` when it is not a valid amount."""
+    if isinstance(value, (Amount, str, Decimal)) or (
+        isinstance(value, int) and not isinstance(value, bool)
+    ):
+        try:
+            return Amount.of(value)
+        except InvalidPaymentDataError:
+            return None
+    return None

python_myanmar_payments/_cache.py

@@ -0,0 +1,80 @@
+"""Access token caches (used by Yoma MMQR)."""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Protocol, runtime_checkable
+
+__all__ = ["AsyncTokenCache", "MemoryTokenCache", "TokenCache"]
+
+
+@runtime_checkable
+class TokenCache(Protocol):
+    """Stores access tokens between calls.
+
+    Implement it on top of Redis or similar to share tokens between processes.
+    """
+
+    def get(self, key: str) -> str | None:
+        """The cached value, or ``None`` when it is missing or expired."""
+
+    def set(self, key: str, value: str, ttl_seconds: int) -> None:
+        """Stores ``value`` for ``ttl_seconds``; ``0`` or less never expires."""
+
+    def delete(self, key: str) -> None:
+        """Removes ``key``."""
+
+
+@runtime_checkable
+class AsyncTokenCache(Protocol):
+    """A :class:`TokenCache` with coroutine methods, e.g. on ``redis.asyncio``.
+
+    Only :class:`~python_myanmar_payments.AsyncYomaMmqr` accepts it.
+    """
+
+    async def get(self, key: str) -> str | None:
+        """The cached value, or ``None`` when it is missing or expired."""
+
+    async def set(self, key: str, value: str, ttl_seconds: int) -> None:
+        """Stores ``value`` for ``ttl_seconds``; ``0`` or less never expires."""
+
+    async def delete(self, key: str) -> None:
+        """Removes ``key``."""
+
+
+class MemoryTokenCache:
+    """The default :class:`TokenCache`: a dict that lives as long as the process.
+
+    Share one gateway (or one cache) across requests so the token is reused.
+    Thread-safe.
+    """
+
+    def __init__(self) -> None:
+        self._items: dict[str, tuple[str, float | None]] = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> str | None:
+        with self._lock:
+            item = self._items.get(key)
+            if item is None:
+                return None
+            value, expires_at = item
+            if expires_at is not None and time.monotonic() >= expires_at:
+                del self._items[key]
+                return None
+            return value
+
+    def set(self, key: str, value: str, ttl_seconds: int) -> None:
+        with self._lock:
+            expires_at = time.monotonic() + ttl_seconds if ttl_seconds > 0 else None
+            self._items[key] = (value, expires_at)
+
+    def delete(self, key: str) -> None:
+        with self._lock:
+            self._items.pop(key, None)
+
+    def clear(self) -> None:
+        """Removes every entry."""
+        with self._lock:
+            self._items.clear()

python_myanmar_payments/_callback.py

@@ -0,0 +1,188 @@
+"""The incoming gateway request that callbacks are verified against."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from types import MappingProxyType
+from typing import Any
+from urllib.parse import parse_qsl
+
+from ._json import LosslessObject, dumps, parse_object, to_plain_object
+
+__all__ = ["BodyInput", "CallbackRequest", "HeadersInput", "QueryInput"]
+
+HeaderValue = str | Sequence[str] | None
+
+HeadersInput = Mapping[str, HeaderValue] | Iterable[tuple[str, str]]
+"""Headers as a mapping (Django, Flask, Starlette and plain dicts) or ``(name, value)`` pairs."""
+
+QueryInput = str | bytes | Mapping[str, HeaderValue] | Iterable[tuple[str, str]]
+"""A query string (``str`` or ``bytes``), a mapping of values or ``(name, value)`` pairs."""
+
+BodyInput = bytes | bytearray | memoryview | str
+"""A request body: raw bytes (preferred) or text."""
+
+# JavaScript's String.prototype.trim() whitespace, which includes the byte order mark.
+_WHITESPACE = "".join(
+    chr(code)
+    for code in (
+        *(0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x20, 0xA0, 0x1680),
+        *range(0x2000, 0x200B),
+        *(0x2028, 0x2029, 0x202F, 0x205F, 0x3000, 0xFEFF),
+    )
+)
+
+
+class CallbackRequest:
+    """An incoming request from a gateway (a server callback or a browser return).
+
+    Signatures are verified against what the gateway actually sent, so build it
+    from the real request: the raw body bytes, the headers and the query string.
+
+    .. code-block:: python
+
+        CallbackRequest(body=request.body, headers=request.headers,
+                        query=request.META["QUERY_STRING"])
+    """
+
+    __slots__ = ("_headers", "_query", "raw_body")
+
+    raw_body: bytes
+    """The raw request body exactly as received."""
+
+    def __init__(
+        self,
+        body: BodyInput | None = None,
+        headers: HeadersInput | None = None,
+        query: QueryInput | None = None,
+    ) -> None:
+        if body is None:
+            self.raw_body = b""
+        elif isinstance(body, str):
+            self.raw_body = body.encode("utf-8", errors="surrogatepass")
+        else:
+            self.raw_body = bytes(body)
+        self._headers: Mapping[str, str] = MappingProxyType(_normalize_headers(headers))
+        self._query: Mapping[str, str] = MappingProxyType(_normalize_query(query))
+
+    @classmethod
+    def from_json(
+        cls, payload: Mapping[str, Any], headers: HeadersInput | None = None
+    ) -> CallbackRequest:
+        """Builds a request from a decoded payload, encoded as a JSON body.
+
+        Use it to replay a callback stored as JSON. Decimals are written as
+        strings.
+        """
+        merged = {**_normalize_headers(headers), "content-type": "application/json"}
+        return cls(body=dumps(payload), headers=merged)
+
+    @property
+    def body(self) -> str:
+        """The raw request body, decoded as UTF-8."""
+        return self.raw_body.decode("utf-8", errors="replace")
+
+    @property
+    def headers(self) -> Mapping[str, str]:
+        """The request headers, with lowercase names. Repeated headers are joined with ``, ``."""
+        return self._headers
+
+    @property
+    def query(self) -> Mapping[str, str]:
+        """The query string parameters (the first value of each)."""
+        return self._query
+
+    def header(self, name: str) -> str | None:
+        """The named header, matched case-insensitively, or ``None``."""
+        return self._headers.get(name.lower())
+
+    def parsed_body(self) -> dict[str, Any]:
+        """The body decoded as JSON or as a urlencoded form.
+
+        JSON numbers keep their exact text as strings, e.g. ``"1000.50"``.
+        """
+        return to_plain_object(lossless_body(self))
+
+    def input(self) -> dict[str, Any]:
+        """The parsed body merged over the query string."""
+        return to_plain_object(lossless_input(self))
+
+    def query_input(self) -> dict[str, Any]:
+        """The query string merged over the parsed body."""
+        return to_plain_object(lossless_query_input(self))
+
+    def __repr__(self) -> str:
+        return (
+            f"CallbackRequest(body={self.body!r}, headers={dict(self._headers)!r}, "
+            f"query={dict(self._query)!r})"
+        )
+
+
+def lossless_body(request: CallbackRequest) -> LosslessObject:
+    """The body as JSON (numbers kept exact) or a form, or ``{}``."""
+    body = request.body.strip(_WHITESPACE)
+    if body == "":
+        return {}
+    json = parse_object(body)
+    if json is not None:
+        return json
+    return dict(_first_values(parse_qsl(body, keep_blank_values=True)))
+
+
+def lossless_input(request: CallbackRequest) -> LosslessObject:
+    """The parsed body merged over the query string."""
+    return {**request.query, **lossless_body(request)}
+
+
+def lossless_query_input(request: CallbackRequest) -> LosslessObject:
+    """The query string merged over the parsed body."""
+    return {**lossless_body(request), **request.query}
+
+
+def _first_values(pairs: Iterable[tuple[str, str]]) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for key, value in pairs:
+        result.setdefault(key, value)
+    return result
+
+
+def _pairs(source: Any) -> Iterable[tuple[str, Any]]:
+    items = getattr(source, "items", None)
+    if callable(items):
+        return list(items())
+    return list(source)
+
+
+def _normalize_headers(headers: HeadersInput | None) -> dict[str, str]:
+    result: dict[str, str] = {}
+    if headers is None:
+        return result
+    for name, value in _pairs(headers):
+        if value is None:
+            continue
+        text = value if isinstance(value, str) else ", ".join(value)
+        key = str(name).lower()
+        result[key] = text if key not in result else f"{result[key]}, {text}"
+    return result
+
+
+def _normalize_query(query: QueryInput | None) -> dict[str, str]:
+    if query is None:
+        return {}
+    if isinstance(query, bytes):
+        query = query.decode("utf-8", errors="replace")
+    if isinstance(query, str):
+        text = query[1:] if query.startswith("?") else query
+        return _first_values(parse_qsl(text, keep_blank_values=True))
+    lists = getattr(query, "lists", None)
+    if callable(lists):  # Django's QueryDict and Werkzeug's MultiDict.
+        return {key: values[0] for key, values in lists() if values}
+    multi_items = getattr(query, "multi_items", None)
+    if callable(multi_items):  # Starlette's QueryParams.
+        return _first_values(multi_items())
+    result: dict[str, str] = {}
+    for key, value in _pairs(query):
+        first = value if isinstance(value, str) or value is None else next(iter(value), None)
+        if first is not None:
+            result.setdefault(key, first)
+    return result

python_myanmar_payments/_errors.py

@@ -0,0 +1,94 @@
+"""The errors this package raises."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any
+
+__all__ = [
+    "ApiError",
+    "ConfigurationError",
+    "InvalidPaymentDataError",
+    "PaymentError",
+    "SignatureVerificationError",
+]
+
+
+class PaymentError(Exception):
+    """Base class of every error raised by this package."""
+
+
+class InvalidPaymentDataError(PaymentError):
+    """Raised when payment data has values the gateway would reject.
+
+    Raised before any request is sent.
+    """
+
+    errors: Mapping[str, str]
+    """Field name to error message, e.g. ``{"amount": "The amount field is required."}``."""
+
+    def __init__(self, errors: Mapping[str, str]) -> None:
+        messages = [errors[field] for field in sorted(errors)]
+        super().__init__(f"Invalid payment data: {' '.join(messages)}")
+        self.errors = MappingProxyType(dict(errors))
+
+
+class ApiError(PaymentError):
+    """Raised when a gateway rejects a request or answers with an error.
+
+    This includes errors sent with HTTP 200, and gateways that cannot be reached
+    (the network error is chained as ``__cause__``).
+    """
+
+    gateway_code: str | None
+    """The gateway's own error code, e.g. ``ORDER_ID_USED`` or ``09``."""
+    gateway_message: str | None
+    """The gateway's own error message."""
+    http_status: int
+    """The HTTP status of the response, or ``0`` when no response was received."""
+    raw: Mapping[str, Any]
+    """The decoded response body."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        gateway_code: str | None = None,
+        gateway_message: str | None = None,
+        http_status: int = 0,
+        raw: Mapping[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.gateway_code = gateway_code
+        self.gateway_message = gateway_message
+        self.http_status = http_status
+        self.raw = raw if raw is not None else {}
+
+
+class SignatureVerificationError(PaymentError):
+    """Raised when a callback, return redirect or gateway response fails verification.
+
+    Never act on its payload.
+    """
+
+    raw: Mapping[str, Any]
+    """The unverified payload, for logging only."""
+
+    def __init__(self, message: str, raw: Mapping[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.raw = raw if raw is not None else {}
+
+
+class ConfigurationError(PaymentError):
+    """Raised when a gateway is missing a credential or setting it needs."""
+
+    gateway: str
+    """The gateway, e.g. ``kbz_pay``."""
+    key: str
+    """The missing setting, e.g. ``app_key``."""
+
+    def __init__(self, gateway: str, key: str) -> None:
+        super().__init__(f"The {gateway} configuration is missing [{key}].")
+        self.gateway = gateway
+        self.key = key