python-myanmar-payments 4.0.0a1__tar.gz

python_myanmar_payments-4.0.0a1/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env
+.DS_Store
+/.idea

python_myanmar_payments-4.0.0a1/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to `python-myanmar-payments` will be documented in this file.
+
+## v4.0.0 - Unreleased
+
+Initial release. The version number matches the other Laranex Myanmar payments packages (`php-myanmar-payments`, `laravel-myanmar-payments`, `go-myanmar-payments`, `node-myanmar-payments`), and the gateways, flows, validation, signing, status maps, results and errors are a port of them, sharing their test vectors. Pre-releases are tagged `v4.0.0-alpha.N` and published to PyPI as `4.0.0aN`.
+
+### Added
+- Gateways: KBZ Pay (`pwa`, `qr`, `app`, `status`), Wave Money (`initiate`), AYA Payment Gateway (`services`, `initiate`, `status`, `verify_redirect`), Yoma MMQR (`initiate`, `renew_qr`, `status`, `forget_token`) and CyberSource Secure Acceptance (`initiate`); every gateway validates its payment data (`KbzPay.validate()` and so on) and verifies callbacks with `handle_callback`.
+- A sync and an async client for every gateway that calls an API (`KbzPay` / `AsyncKbzPay`, `WaveMoney` / `AsyncWaveMoney`, `AyaPay` / `AsyncAyaPay`, `YomaMmqr` / `AsyncYomaMmqr`), sharing one implementation of signing, validation and response parsing. `CyberSource` makes no network calls and serves both.
+- `httpx` is the only runtime dependency: pass your own `httpx.Client` / `httpx.AsyncClient` as `http_client`, or let the gateway create one with a 30 second `timeout` and close it with `close()` / `aclose()` or a `with` / `async with` block.
+- Exact `Amount` type (`Amount.kyat()`, `Amount.parse()`, `Amount.of()`) kept as decimal text, so amounts never pass through a float; payment data also takes a whole `int`, decimal text or a `Decimal`, and rejects floats. Decimals are accepted only where the gateway documents them (KBZ Pay up to 2 places, CyberSource any); every gateway except CyberSource is MMK only.
+- Typed payment data dataclasses (`KbzPayPaymentData`, `WaveMoneyPaymentData` with `WaveMoneyItem`, `AyaPayPaymentData`, `YomaMmqrPaymentData`, `CyberSourcePaymentData`) and a config class per gateway with `from_env()` (default `os.environ`), reading the same `*_SANDBOX`, credential and URL variables as the PHP, Laravel, Go and Node packages; a missing credential raises `ConfigurationError`. `sandbox` also takes text read like `*_SANDBOX` (`false`, `0`, `f`, `no` or `off` select production). Gateways, `MyanmarPayments` and `AsyncMyanmarPayments` take config objects or mappings of their keyword arguments; the facades build every gateway lazily, also from the environment.
+- Result classes: `RedirectPayment`, `FormPayment` (with `to_html()`), `QrPayment` (with `qr_image_data_uri()`) and `AppPayment` (with `to_dict()`); `PaymentCallback` (with a gateway-independent `PaymentStatus` and the `Acknowledgement` each gateway expects, in its `acknowledgement` attribute) and `PaymentStatusResult`.
+- `CallbackRequest(body=..., headers=..., query=...)` takes the raw body bytes, headers and query string from Django, Flask, FastAPI or any other framework; `CallbackRequest.from_json()` replays a stored callback. JSON numbers in callbacks are read without a float conversion, so signatures and amounts keep the gateway's exact text, and `raw` (like `parsed_body()`, `input()` and error `raw`) holds every JSON number as its exact text, e.g. `"1000.50"`.
+- Errors: `PaymentError` and its subclasses `InvalidPaymentDataError` (per-field `errors`), `ApiError` (`gateway_code`, `gateway_message`, `http_status`, `raw`, network errors chained as `__cause__`), `SignatureVerificationError` and `ConfigurationError`.
+- An injectable `TokenCache` (or `AsyncTokenCache` for the async client) with a thread-safe in-memory default for Yoma's access token; concurrent calls share one token request.
+- Callback verification is the same in every Laranex payments SDK, checked by shared vectors (`tests/fixtures/parity/vectors.json`): numbers sign as the exact text sent, booleans as `true` / `false`, and a nested value (object or list) in a signed field fails verification.
+- `Amount.equals()` and `==` compare by value, ignoring leading zeros and trailing fractional zeros (`"01000"` equals `Amount.kyat(1000)`); text that is not plain digits never equals.
+- CyberSource callbacks trust only the fields listed in `signed_field_names`: `decision` and `req_reference_number` must be signed, and unsigned fields are left out of the result and `raw`.
+- AYA Pay reads a `payload` whose `+` signs became spaces in an unencoded return query string, with or without base64 padding; partial padding, other alphabets and payloads that are not UTF-8 are rejected.
+- Yoma MMQR caches its token under `myanmar-payments.yoma-mmqr.token.<sha256 of base URL|client id>`, the same key as the PHP, Go and Node SDKs, so services in different languages can share one cache.
+- Callback, return and cancel URLs only need to be valid absolute http or https URLs; there is no HTTPS-only rule (gateways may still require HTTPS in production).
+- Wave Money's sandbox is `https://preprodpayments.wavemoney.io:8107`, with checkout at `https://preprodpayments.wavemoney.io/authenticate`.
+- Fully typed (`py.typed`, `mypy --strict`).
+- Agent skill in `skills/python-myanmar-payments` so coding agents use the package correctly; install it with `npx skills add laranex/python-myanmar-payments`.
+- Requires Python 3.10 or higher.

python_myanmar_payments-4.0.0a1/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Nay Thu Khant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_myanmar_payments-4.0.0a1/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.5
+Name: python-myanmar-payments
+Version: 4.0.0a1
+Summary: 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.
+Project-URL: Homepage, https://laranex.vercel.app/python-myanmar-payments
+Project-URL: Documentation, https://laranex.vercel.app/python-myanmar-payments
+Project-URL: Repository, https://github.com/laranex/python-myanmar-payments
+Project-URL: Issues, https://github.com/laranex/python-myanmar-payments/issues
+Project-URL: Changelog, https://github.com/laranex/python-myanmar-payments/blob/dev/CHANGELOG.md
+Author-email: Nay Thu Khant <naythukhant644@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Keywords: aya-pay,cybersource,kbzpay,laranex,mmqr,myanmar,payment-gateway,payments,python-myanmar-payments,wave-money,wavepay,yoma
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25
+Description-Content-Type: text/markdown
+
+# Python Myanmar Payments
+
+[![PyPI](https://img.shields.io/pypi/v/python-myanmar-payments.svg?style=flat-square)](https://pypi.org/project/python-myanmar-payments/)
+[![Tests](https://github.com/laranex/python-myanmar-payments/actions/workflows/tests.yml/badge.svg)](https://github.com/laranex/python-myanmar-payments/actions/workflows/tests.yml)
+[![Python](https://img.shields.io/pypi/pyversions/python-myanmar-payments.svg?style=flat-square)](https://pypi.org/project/python-myanmar-payments/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE.md)
+
+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. Built for humans and AI agents.
+
+## Documentation
+
+Full documentation, including installation, usage and the AI agent skill, lives at **[laranex.vercel.app/python-myanmar-payments](https://laranex.vercel.app/python-myanmar-payments)**.

python_myanmar_payments-4.0.0a1/README.md

@@ -0,0 +1,12 @@
+# Python Myanmar Payments
+
+[![PyPI](https://img.shields.io/pypi/v/python-myanmar-payments.svg?style=flat-square)](https://pypi.org/project/python-myanmar-payments/)
+[![Tests](https://github.com/laranex/python-myanmar-payments/actions/workflows/tests.yml/badge.svg)](https://github.com/laranex/python-myanmar-payments/actions/workflows/tests.yml)
+[![Python](https://img.shields.io/pypi/pyversions/python-myanmar-payments.svg?style=flat-square)](https://pypi.org/project/python-myanmar-payments/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE.md)
+
+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. Built for humans and AI agents.
+
+## Documentation
+
+Full documentation, including installation, usage and the AI agent skill, lives at **[laranex.vercel.app/python-myanmar-payments](https://laranex.vercel.app/python-myanmar-payments)**.

python_myanmar_payments-4.0.0a1/pyproject.toml

@@ -0,0 +1,107 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "python-myanmar-payments"
+dynamic = ["version"]
+description = "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."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE.md"]
+requires-python = ">=3.10"
+authors = [{ name = "Nay Thu Khant", email = "naythukhant644@gmail.com" }]
+keywords = [
+    "laranex",
+    "python-myanmar-payments",
+    "myanmar",
+    "payments",
+    "payment-gateway",
+    "kbzpay",
+    "wave-money",
+    "wavepay",
+    "aya-pay",
+    "yoma",
+    "mmqr",
+    "cybersource",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.25"]
+
+[project.urls]
+Homepage = "https://laranex.vercel.app/python-myanmar-payments"
+Documentation = "https://laranex.vercel.app/python-myanmar-payments"
+Repository = "https://github.com/laranex/python-myanmar-payments"
+Issues = "https://github.com/laranex/python-myanmar-payments/issues"
+Changelog = "https://github.com/laranex/python-myanmar-payments/blob/dev/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.13",
+    "pytest>=8.3",
+    "pytest-cov>=6.0",
+    "ruff>=0.8",
+]
+
+[tool.hatch.version]
+path = "src/python_myanmar_payments/_version.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/skills",
+    "/CHANGELOG.md",
+    "/LICENSE.md",
+    "/README.md",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/python_myanmar_payments"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["--strict-markers", "--strict-config", "-ra"]
+xfail_strict = true
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+branch = true
+source = ["python_myanmar_payments"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+fail_under = 100
+exclude_also = ["if TYPE_CHECKING:"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+files = ["src", "tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "UP", "SIM", "RUF", "C4", "PT", "PIE", "RET", "N"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["N802"]

python_myanmar_payments-4.0.0a1/skills/python-myanmar-payments/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: python-myanmar-payments
+description: >
+  Integrate Myanmar payment gateways (KBZ Pay, Wave Money, AYA Pay, Yoma MMQR, CyberSource) in a Python app (Django, Flask, FastAPI or plain Python) with python-myanmar-payments.
+license: MIT
+metadata:
+  author: Nay Thu Khant
+---
+
+# Python Myanmar Payments
+
+## When to use
+
+Use this skill when a Python app takes payments through KBZ Pay, Wave Money, AYA Payment Gateway, Yoma MMQR or CyberSource. Start payments and verify callbacks with the package's typed API; never build gateway signatures by hand. It works the same in Django, Flask, FastAPI or plain Python.
+
+## Install
+
+```bash
+pip install python-myanmar-payments
+```
+
+Requires Python 3.10+ and depends only on `httpx`. Import everything from `python_myanmar_payments`. Every gateway that calls an API has a sync class (`KbzPay`, `WaveMoney`, `AyaPay`, `YomaMmqr`) and an async twin (`AsyncKbzPay`, `AsyncWaveMoney`, `AsyncAyaPay`, `AsyncYomaMmqr`) with the same methods, awaited; use the async ones inside an event loop. `CyberSource` makes no network calls and serves both.
+
+## Configure
+
+`MyanmarPayments.from_env()` reads `KBZ_PAY_*`, `WAVE_MONEY_*`, `AYA_PAY_*` (or `AYA_PGW_*`), `YOMA_MMQR_*` and `CYBER_SOURCE_*` from `os.environ` (the same variables as the PHP, Go and Node SDKs). `sandbox` defaults to `True`; set `*_SANDBOX=false` (or `sandbox=False`) in production.
+
+```python
+from python_myanmar_payments import MyanmarPayments
+
+payments = MyanmarPayments.from_env()  # create once, share across requests
+kbz = payments.kbz_pay()  # also wave_money(), aya_pay(), yoma_mmqr(), cyber_source()
+```
+
+- Or build one gateway: `KbzPay(KbzPayConfig(app_id=..., app_key=..., merchant_code=...))`, `KbzPay.from_env()` or `KbzPay(KbzPayConfig.from_env())`; in async code use `AsyncMyanmarPayments.from_env()` and `AsyncKbzPay`.
+- Or pass the settings directly: gateways and `MyanmarPayments(kbz_pay={"app_id": ..., "app_key": ..., "merchant_code": ...})` take config objects or mappings of their keyword arguments; a string `sandbox` such as `"false"` is read like the variable.
+- Options (keyword arguments): `http_client` (your own `httpx.Client` / `httpx.AsyncClient`) and `timeout` (seconds, default 30); close the clients the package created with `payments.close()` / `await payments.aclose()` or a `with` block. Yoma and the facades also take `token_cache` (any `TokenCache`, default `MemoryTokenCache`; back it with Redis when you run several processes).
+- A missing credential raises `ConfigurationError` (`gateway`, `key`).
+
+## Use
+
+### Amounts
+
+Amounts are `Amount.kyat(1000)`, `Amount.parse("1000.50")`, a whole `int`, decimal text or a `Decimal`; never a float such as `10.5`. Only KBZ Pay (up to 2 decimals) and CyberSource accept decimals; Wave, AYA and Yoma take whole kyat. Invalid data raises `InvalidPaymentDataError` with `errors` per field (`order_id`, `amount`, ...), before any request is sent. Compare a gateway's amount by value with `amount.equals(callback.amount)`.
+
+### Start a payment
+
+Each gateway takes a data object (`KbzPayPaymentData`, `WaveMoneyPaymentData` with `WaveMoneyItem`s, `AyaPayPaymentData` with an `AyaPayMethod`, `YomaMmqrPaymentData`, `CyberSourcePaymentData` with a `CyberSourceTransactionType`) and returns a typed result:
+
+```python
+from python_myanmar_payments import Amount, KbzPayPaymentData
+
+payment = kbz.pwa(
+    KbzPayPaymentData(
+        order_id="ORDER_1",
+        amount=Amount.kyat(1000),
+        callback_url="https://shop.test/payments/kbz/callback",
+    )
+)
+return redirect(payment.url)
+```
+
+- `RedirectPayment` (`url`) from `kbz.pwa(data)` and `wave.initiate(data)`. Wave fills `data.merchant_reference_id` when empty; store it.
+- `FormPayment` from `aya.initiate(data)` and `cyber_source.initiate(data)` (no network call, never awaited): return `payment.to_html()` as an auto-submitting page, or render `action`, `fields` and `enctype` yourself.
+- `QrPayment` from `kbz.qr(data)` (encode `qr_string`) and `yoma.initiate(data)` (`qr_image_data_uri()`, `expires_at`, `reference`). A Yoma QR lives `YomaMmqr.QR_LIFETIME_SECONDS` (120); renew it with `yoma.renew_qr(order_id)`.
+- `AppPayment` from `kbz.app(data)`: send `payment.to_dict()` (`orderId`, `orderInfo`, `sign`, `signType`) to your mobile app.
+
+AYA needs a channel: `aya.services()` lists `AyaPayService` entries (`key`, `supports(method)`), then `aya.initiate(AyaPayPaymentData(order_id="ORDER123", amount=1000, channel="kbz_pay", method=AyaPayMethod.QR))`.
+
+### Handle the callback
+
+Build a `CallbackRequest` from the raw request, verify it, then reply:
+
+```python
+from python_myanmar_payments import CallbackRequest, SignatureVerificationError
+
+request = CallbackRequest(
+    body=django_request.body,  # Flask: request.get_data(); FastAPI: await request.body()
+    headers=django_request.headers,
+    query=django_request.META["QUERY_STRING"],  # Flask: request.query_string
+)
+try:
+    callback = kbz.handle_callback(request)
+except SignatureVerificationError:
+    return HttpResponse("invalid signature", status=400)
+if callback.is_successful():
+    ...  # compare callback.amount with the order, then fulfill callback.order_id once
+ack = callback.acknowledgement
+return HttpResponse(ack.body, status=ack.status, headers=ack.headers)
+```
+
+- Give the package the raw body bytes, the headers and the query string; `handle_callback()` and `verify_redirect()` are plain methods on the async classes too.
+- Check AYA's browser return with `aya.verify_redirect(request)`.
+- For production, store the verified callback, acknowledge immediately, then process it once in the background.
+
+### Check status and handle errors
+
+- `kbz.status(order_id)`, `aya.status(order_id)` and `yoma.status(reference)` return `PaymentStatusResult` with `status` and `is_successful()`. Wave Money and CyberSource have no status API.
+- Statuses: `PaymentStatus.SUCCESSFUL`, `PENDING`, `FAILED`, `CANCELED`, `EXPIRED`, `UNKNOWN`; `status.is_final()`.
+- Gateway failures raise `ApiError` (`gateway_code`, `gateway_message`, `http_status`, `raw`; network errors are chained as `__cause__`). All errors extend `PaymentError`.
+
+## Test your app
+
+- Pass an `httpx.Client(transport=httpx.MockTransport(handler))` (or an `httpx.AsyncClient`) as `http_client`, or mock with `respx`.
+- Replay a stored callback with `CallbackRequest.from_json(payload, headers)` or `CallbackRequest(body=..., headers=..., query=...)`; it is still signature-checked.
+- To test your own fulfillment code, build `PaymentCallback(order_id="ORDER_1", status=PaymentStatus.SUCCESSFUL, gateway_status="PAY_SUCCESS")` yourself.
+
+## Avoid
+
+- Fulfilling orders from return pages or query strings; fulfill only from a verified callback or a status check.
+- Treating `PENDING` or `UNKNOWN` as paid.
+- Passing floats or `float(price)` as amounts; use `Amount.parse()` or a `Decimal`.
+- Building the `CallbackRequest` from `request.json` / `request.POST` instead of the raw body.
+- Reusing a Wave `merchant_reference_id`, or calling Yoma `initiate()` twice for one order (use `renew_qr()`).
+- Opening a KBZ Pay PWA link outside a phone with the KBZ Pay app.

python_myanmar_payments-4.0.0a1/src/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-4.0.0a1/src/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