monapay 0.1.0__tar.gz

monapay-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The MONA Group
+
+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.

monapay-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: monapay
+Version: 0.1.0
+Summary: SDK Python zero-dependency cho MONA Pay
+Author-email: The MONA Group <info@themona.global>
+License: MIT
+Project-URL: Documentation, https://monapay.vn/docs
+Project-URL: Repository, https://github.com/monapay/monapay-python
+Keywords: monapay,vietqr,virtual-account,payment,webhook
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# monapay
+
+MONA Pay là cổng thanh toán và API ngân hàng của The MONA Group, giúp doanh nghiệp Việt Nam nhận và xác nhận tiền chuyển khoản theo thời gian thực qua tài khoản ảo (VA), VietQR, webhook và Telegram — thiết kế để cả lập trình viên lẫn AI agent tích hợp trong vài phút.
+
+SDK Python đồng bộ, chỉ dùng standard library. MONA Pay miễn phí hoàn toàn.
+
+## Cài đặt
+
+```bash
+pip install monapay
+```
+
+## Bắt đầu nhanh
+
+```python
+import os
+from monapay import MonaPay
+
+mona = MonaPay(
+    os.environ["MONA_USERNAME"],
+    os.environ["MONA_PASSWORD"],
+    client_secret=os.getenv("MONA_CLIENT_SECRET"),
+)
+
+# Tự login và giữ token.
+print(mona.me())
+
+# Lần đầu: secret chỉ hiện một lần. SDK giữ key mới cho instance hiện tại.
+key = mona.keys.generate("Web ban hang")
+print("Lưu MONA_CLIENT_SECRET an toàn:", key["client_secret"])
+
+mona.webhooks.create({
+    "name": "Web ban hang",
+    "webhook_url": "https://shop.vn/webhooks/monapay",
+    "auth_type": "HMAC_SHA256",
+    "secret_key": os.environ["MONA_WEBHOOK_SECRET"],
+    "payload_format": "application/json",
+})
+
+qr = mona.qr.generate({
+    "ownerNumber": "123456789", "ownerType": "ORG",
+    "merchantId": "MC00012345", "terminalId": "TM0001", "orderId": "DH10234",
+    "virtualAccountPrefix": "MONA", "beneficiaryName": "CONG TY ABC",
+    "amount": 2500000, "description": "Thanh toan DH10234",
+})
+print(qr["qr_data_url"])
+```
+
+Client tự login lại và thử request đúng một lần khi gặp HTTP 401. Các method trả trực tiếp trường `data`; `ApiError` có `status` và `body`.
+
+Các nhóm method: `keys`, `va`, `bank_accounts`, `qr`, `transactions`, `webhooks`, `webhook_logs`. Tên method dùng snake_case, ví dụ `va.register_notification(...)` và `transactions.retry(id, target_type="WEBHOOK", target_id=...)`.
+
+Đọc hết các trang giao dịch:
+
+```python
+for tx in mona.iter_transactions("MONA0000010234", limit=100):
+    print(tx["transaction_code"], tx["amount"])
+```
+
+## Xác thực webhook
+
+Luôn truyền đúng `request.body` dạng bytes, không parse rồi encode lại.
+
+```python
+from monapay import verify_webhook
+
+result = verify_webhook(raw_body, headers, os.environ["MONA_WEBHOOK_SECRET"])
+if not result.ok:
+    return {"reason": result.reason}, 401
+save_once(result.payload["transaction_code"], result.payload)
+```
+
+Ví dụ nhận webhook cho Flask, FastAPI và Django nằm trong `examples/`. Dùng `transaction_code` làm unique key để chống xử lý trùng.
+
+Tài liệu: https://monapay.vn/docs · AI/LLM: https://monapay.vn/llms.txt · Hotline 1900 636 648 · info@themona.global
+
+## Test
+
+Từ thư mục chứa `python/`:
+
+```bash
+python3 -m unittest discover python/tests
+```
+
+License MIT.

monapay-0.1.0/README.md

@@ -0,0 +1,85 @@
+# monapay
+
+MONA Pay là cổng thanh toán và API ngân hàng của The MONA Group, giúp doanh nghiệp Việt Nam nhận và xác nhận tiền chuyển khoản theo thời gian thực qua tài khoản ảo (VA), VietQR, webhook và Telegram — thiết kế để cả lập trình viên lẫn AI agent tích hợp trong vài phút.
+
+SDK Python đồng bộ, chỉ dùng standard library. MONA Pay miễn phí hoàn toàn.
+
+## Cài đặt
+
+```bash
+pip install monapay
+```
+
+## Bắt đầu nhanh
+
+```python
+import os
+from monapay import MonaPay
+
+mona = MonaPay(
+    os.environ["MONA_USERNAME"],
+    os.environ["MONA_PASSWORD"],
+    client_secret=os.getenv("MONA_CLIENT_SECRET"),
+)
+
+# Tự login và giữ token.
+print(mona.me())
+
+# Lần đầu: secret chỉ hiện một lần. SDK giữ key mới cho instance hiện tại.
+key = mona.keys.generate("Web ban hang")
+print("Lưu MONA_CLIENT_SECRET an toàn:", key["client_secret"])
+
+mona.webhooks.create({
+    "name": "Web ban hang",
+    "webhook_url": "https://shop.vn/webhooks/monapay",
+    "auth_type": "HMAC_SHA256",
+    "secret_key": os.environ["MONA_WEBHOOK_SECRET"],
+    "payload_format": "application/json",
+})
+
+qr = mona.qr.generate({
+    "ownerNumber": "123456789", "ownerType": "ORG",
+    "merchantId": "MC00012345", "terminalId": "TM0001", "orderId": "DH10234",
+    "virtualAccountPrefix": "MONA", "beneficiaryName": "CONG TY ABC",
+    "amount": 2500000, "description": "Thanh toan DH10234",
+})
+print(qr["qr_data_url"])
+```
+
+Client tự login lại và thử request đúng một lần khi gặp HTTP 401. Các method trả trực tiếp trường `data`; `ApiError` có `status` và `body`.
+
+Các nhóm method: `keys`, `va`, `bank_accounts`, `qr`, `transactions`, `webhooks`, `webhook_logs`. Tên method dùng snake_case, ví dụ `va.register_notification(...)` và `transactions.retry(id, target_type="WEBHOOK", target_id=...)`.
+
+Đọc hết các trang giao dịch:
+
+```python
+for tx in mona.iter_transactions("MONA0000010234", limit=100):
+    print(tx["transaction_code"], tx["amount"])
+```
+
+## Xác thực webhook
+
+Luôn truyền đúng `request.body` dạng bytes, không parse rồi encode lại.
+
+```python
+from monapay import verify_webhook
+
+result = verify_webhook(raw_body, headers, os.environ["MONA_WEBHOOK_SECRET"])
+if not result.ok:
+    return {"reason": result.reason}, 401
+save_once(result.payload["transaction_code"], result.payload)
+```
+
+Ví dụ nhận webhook cho Flask, FastAPI và Django nằm trong `examples/`. Dùng `transaction_code` làm unique key để chống xử lý trùng.
+
+Tài liệu: https://monapay.vn/docs · AI/LLM: https://monapay.vn/llms.txt · Hotline 1900 636 648 · info@themona.global
+
+## Test
+
+Từ thư mục chứa `python/`:
+
+```bash
+python3 -m unittest discover python/tests
+```
+
+License MIT.

monapay-0.1.0/monapay/__init__.py

@@ -0,0 +1,7 @@
+"""MONA Pay Python SDK."""
+
+from .client import ApiError, MonaPay
+from .webhook import WebhookResult, verify_webhook
+
+__all__ = ["ApiError", "MonaPay", "WebhookResult", "verify_webhook"]
+__version__ = "0.1.0"

monapay-0.1.0/monapay/client.py

@@ -0,0 +1,312 @@
+"""Synchronous, standard-library-only MONA Pay client."""
+
+import json
+import threading
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Iterator, Mapping, Optional
+
+
+DEFAULT_BASE_URL = "https://api.monapay.vn"
+
+
+class ApiError(RuntimeError):
+    """Error returned by MONA Pay or raised while decoding its response."""
+
+    def __init__(self, message: str, status: Optional[int] = None, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+def _segment(value: Any) -> str:
+    return urllib.parse.quote(str(value), safe="")
+
+
+def _log_query(options: Mapping[str, Any]) -> Dict[str, Any]:
+    return {
+        "status": options.get("status"),
+        "from_date": options.get("from_date"),
+        "to_date": options.get("to_date"),
+        "page": options.get("page"),
+        "limit": options.get("limit"),
+    }
+
+
+class _Resource:
+    def __init__(self, client: "MonaPay"):
+        self._client = client
+
+
+class Keys(_Resource):
+    def generate(self, name: str = "Default Key") -> Any:
+        data = self._client._request("POST", "/api/v1/client-keys/generate", body={"name": name})
+        if not self._client.client_secret and isinstance(data, dict):
+            self._client.client_secret = data.get("client_secret")
+        return data
+
+    def list(self) -> Any:
+        return self._client._request("GET", "/api/v1/client-keys/list")
+
+    def destroy(self, key_id: str) -> Any:
+        return self._client._request("DELETE", "/api/v1/client-keys/destroy/" + _segment(key_id))
+
+
+class VirtualAccounts(_Resource):
+    def register(self, body: Mapping[str, Any]) -> Any:
+        return self._client._request("POST", "/api/v1/acb/virtual-account/registration", body=body)
+
+    def verify(self, request_id: str, code: str) -> Any:
+        return self._client._request(
+            "POST",
+            "/api/v1/acb/{}/virtual-account/verification".format(_segment(request_id)),
+            body={"code": code},
+        )
+
+    def register_notification(self, va_id: str, body: Mapping[str, Any]) -> Any:
+        return self._client._request(
+            "POST",
+            "/api/v1/acb/{}/notification/registration".format(_segment(va_id)),
+            body=body,
+        )
+
+    def verify_notification(self, request_id: str, code: str) -> Any:
+        return self._client._request(
+            "POST",
+            "/api/v1/acb/{}/notification/verification".format(_segment(request_id)),
+            body={"code": code},
+        )
+
+    def list(self, bank_account_id: str) -> Any:
+        return self._client._request(
+            "GET", "/api/v1/acb/{}/virtual-account/retrieve".format(_segment(bank_account_id))
+        )
+
+
+class BankAccounts(_Resource):
+    def list(self) -> Any:
+        return self._client._request("GET", "/api/v1/client/bank-accounts")
+
+
+class QrPayments(_Resource):
+    def generate(self, body: Mapping[str, Any]) -> Any:
+        return self._client._request("POST", "/api/v1/acb/qr-payment/generate", body=body)
+
+    def cancel(self, qr_code_id: str, body: Optional[Mapping[str, Any]] = None) -> Any:
+        return self._client._request(
+            "DELETE",
+            "/api/v1/acb/qr-payment/{}/cancellation".format(_segment(qr_code_id)),
+            body=body,
+        )
+
+
+class Transactions(_Resource):
+    def list(
+        self, virtual_account_number: str, page: int = 1, limit: int = 100
+    ) -> Any:
+        if not virtual_account_number:
+            raise ValueError("virtual_account_number là bắt buộc")
+        return self._client._request(
+            "GET",
+            "/api/v1/acb/virtual-account/transactions",
+            query={
+                "virtual_account_number": virtual_account_number,
+                "page": page,
+                "limit": limit,
+            },
+        )
+
+    def iterate(
+        self, virtual_account_number: str, page: int = 1, limit: int = 100
+    ) -> Iterator[Any]:
+        current_page = page
+        while True:
+            result = self.list(virtual_account_number, page=current_page, limit=limit)
+            for transaction in (result or {}).get("data", []):
+                yield transaction
+            if "has_next" in (result or {}):
+                has_next = bool(result["has_next"])
+            else:
+                has_next = current_page < int((result or {}).get("last_page", current_page))
+            if not has_next:
+                return
+            current_page += 1
+
+    def retry(
+        self, transaction_id: str, target_type: str, target_id: Optional[str] = None
+    ) -> Any:
+        body = {"target_type": target_type}
+        if target_id is not None:
+            body["target_id"] = target_id
+        return self._client._request(
+            "POST",
+            "/api/v1/acb/virtual-account/transactions/{}/retry".format(
+                _segment(transaction_id)
+            ),
+            body=body,
+        )
+
+
+class Webhooks(_Resource):
+    def list(self) -> Any:
+        return self._client._request("GET", "/api/v1/client-webhooks")
+
+    def create(self, body: Mapping[str, Any]) -> Any:
+        return self._client._request("POST", "/api/v1/client-webhooks", body=body)
+
+    def update(self, config_id: str, body: Mapping[str, Any]) -> Any:
+        return self._client._request(
+            "PUT", "/api/v1/client-webhooks/" + _segment(config_id), body=body
+        )
+
+    def remove(self, config_id: str) -> Any:
+        return self._client._request(
+            "DELETE", "/api/v1/client-webhooks/" + _segment(config_id)
+        )
+
+    def test(self, body: Mapping[str, Any]) -> Any:
+        return self._client._request("POST", "/api/v1/client-webhooks/test", body=body)
+
+
+class WebhookLogs(_Resource):
+    def list(self, **options: Any) -> Any:
+        return self._client._request(
+            "GET", "/api/v1/webhook-logs", query=_log_query(options)
+        )
+
+    def stats(self, **options: Any) -> Any:
+        return self._client._request(
+            "GET", "/api/v1/webhook-logs/stats", query=_log_query(options)
+        )
+
+
+class MonaPay:
+    """Synchronous MONA Pay API client using urllib."""
+
+    def __init__(
+        self,
+        username: str,
+        password: str,
+        client_secret: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30,
+    ):
+        if not username or not password:
+            raise ValueError("username và password là bắt buộc")
+        self.username = username
+        self.password = password
+        self.client_secret = client_secret
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._access_token = None  # type: Optional[str]
+        self._login_lock = threading.Lock()
+
+        self.keys = Keys(self)
+        self.va = VirtualAccounts(self)
+        self.bank_accounts = BankAccounts(self)
+        self.qr = QrPayments(self)
+        self.transactions = Transactions(self)
+        self.webhooks = Webhooks(self)
+        self.webhook_logs = WebhookLogs(self)
+
+    def me(self) -> Any:
+        return self._request("GET", "/api/v1/client/me")
+
+    def iter_transactions(
+        self, virtual_account_number: str, page: int = 1, limit: int = 100
+    ) -> Iterator[Any]:
+        return self.transactions.iterate(virtual_account_number, page=page, limit=limit)
+
+    def _login(self) -> str:
+        with self._login_lock:
+            if self._access_token:
+                return self._access_token
+            data = self._send(
+                "POST",
+                "/api/v1/client/login",
+                body={"username": self.username, "password": self.password},
+                authenticated=False,
+            )
+            if not isinstance(data, dict) or not data.get("access_token"):
+                raise ApiError("Response đăng nhập không có access_token")
+            self._access_token = data["access_token"]
+            return self._access_token
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Mapping[str, Any]] = None,
+        query: Optional[Mapping[str, Any]] = None,
+        retry: bool = True,
+    ) -> Any:
+        if not self._access_token:
+            self._login()
+        try:
+            return self._send(method, path, body=body, query=query, authenticated=True)
+        except ApiError as error:
+            if error.status == 401 and retry:
+                self._access_token = None
+                self._login()
+                return self._request(method, path, body=body, query=query, retry=False)
+            raise
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Mapping[str, Any]] = None,
+        query: Optional[Mapping[str, Any]] = None,
+        authenticated: bool = True,
+    ) -> Any:
+        clean_query = {key: value for key, value in (query or {}).items() if value is not None}
+        url = self.base_url + path
+        if clean_query:
+            url += "?" + urllib.parse.urlencode(clean_query)
+
+        headers = {"Accept": "application/json"}
+        if authenticated:
+            headers["Authorization"] = "Bearer " + str(self._access_token)
+        if authenticated and method != "GET" and self.client_secret:
+            headers["X-Client-Secret"] = self.client_secret
+        encoded_body = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            encoded_body = json.dumps(body, separators=(",", ":")).encode("utf-8")
+
+        request = urllib.request.Request(
+            url, data=encoded_body, headers=headers, method=method
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                status = response.getcode()
+                raw = response.read()
+        except urllib.error.HTTPError as error:
+            status = error.code
+            raw = error.read()
+        except urllib.error.URLError as error:
+            raise ApiError("Không kết nối được MONA Pay: {}".format(error.reason)) from error
+
+        if raw:
+            try:
+                payload = json.loads(raw.decode("utf-8"))
+            except (UnicodeDecodeError, json.JSONDecodeError) as error:
+                raise ApiError(
+                    "MONA Pay trả response không phải JSON (HTTP {})".format(status),
+                    status=status,
+                    body=raw,
+                ) from error
+        else:
+            payload = {}
+
+        if not 200 <= status < 300 or payload.get("success") is False:
+            detail = payload.get("detail")
+            if not isinstance(detail, str):
+                detail = None
+            raise ApiError(
+                payload.get("message") or detail or "MONA Pay API lỗi HTTP {}".format(status),
+                status=status,
+                body=payload,
+            )
+        return payload.get("data")

monapay-0.1.0/monapay/webhook.py

@@ -0,0 +1,68 @@
+"""MONA Pay webhook signature verification."""
+
+import hashlib
+import hmac
+import json
+import re
+import time
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional
+
+
+@dataclass(frozen=True)
+class WebhookResult:
+    ok: bool
+    reason: Optional[str] = None
+    payload: Any = None
+
+
+def _header(headers: Mapping[str, Any], wanted: str) -> Optional[str]:
+    lowered = wanted.lower()
+    for name, value in headers.items():
+        if str(name).lower() == lowered:
+            if isinstance(value, (list, tuple)):
+                value = value[0] if value else None
+            return None if value is None else str(value)
+    return None
+
+
+def verify_webhook(
+    raw_body: bytes,
+    headers: Mapping[str, Any],
+    secret: str,
+    tolerance: int = 300,
+) -> WebhookResult:
+    """Verify timestamp + HMAC against the exact request bytes, then parse JSON."""
+    if not isinstance(raw_body, bytes):
+        raise TypeError("raw_body phải là bytes")
+    if tolerance < 0:
+        raise ValueError("tolerance phải là số không âm")
+
+    timestamp_text = _header(headers, "x-mona-timestamp")
+    signature = _header(headers, "x-mona-signature")
+    if not timestamp_text:
+        return WebhookResult(False, "missing_timestamp")
+    if not timestamp_text.isdigit():
+        return WebhookResult(False, "invalid_timestamp")
+    timestamp = int(timestamp_text)
+    if abs(int(time.time()) - timestamp) > tolerance:
+        return WebhookResult(False, "timestamp_out_of_tolerance")
+    if not signature:
+        return WebhookResult(False, "missing_signature")
+
+    expected = hmac.new(
+        secret.encode("utf-8"),
+        timestamp_text.encode("ascii") + b"." + raw_body,
+        hashlib.sha256,
+    ).hexdigest()
+    match = re.fullmatch(r"sha256=([0-9a-fA-F]{64})", signature)
+    supplied = match.group(1).lower() if match else "0" * 64
+    valid_signature = hmac.compare_digest(expected, supplied) and match is not None
+    if not valid_signature:
+        return WebhookResult(False, "invalid_signature")
+
+    try:
+        payload = json.loads(raw_body.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return WebhookResult(False, "invalid_json")
+    return WebhookResult(True, payload=payload)

monapay-0.1.0/monapay.egg-info/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: monapay
+Version: 0.1.0
+Summary: SDK Python zero-dependency cho MONA Pay
+Author-email: The MONA Group <info@themona.global>
+License: MIT
+Project-URL: Documentation, https://monapay.vn/docs
+Project-URL: Repository, https://github.com/monapay/monapay-python
+Keywords: monapay,vietqr,virtual-account,payment,webhook
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# monapay
+
+MONA Pay là cổng thanh toán và API ngân hàng của The MONA Group, giúp doanh nghiệp Việt Nam nhận và xác nhận tiền chuyển khoản theo thời gian thực qua tài khoản ảo (VA), VietQR, webhook và Telegram — thiết kế để cả lập trình viên lẫn AI agent tích hợp trong vài phút.
+
+SDK Python đồng bộ, chỉ dùng standard library. MONA Pay miễn phí hoàn toàn.
+
+## Cài đặt
+
+```bash
+pip install monapay
+```
+
+## Bắt đầu nhanh
+
+```python
+import os
+from monapay import MonaPay
+
+mona = MonaPay(
+    os.environ["MONA_USERNAME"],
+    os.environ["MONA_PASSWORD"],
+    client_secret=os.getenv("MONA_CLIENT_SECRET"),
+)
+
+# Tự login và giữ token.
+print(mona.me())
+
+# Lần đầu: secret chỉ hiện một lần. SDK giữ key mới cho instance hiện tại.
+key = mona.keys.generate("Web ban hang")
+print("Lưu MONA_CLIENT_SECRET an toàn:", key["client_secret"])
+
+mona.webhooks.create({
+    "name": "Web ban hang",
+    "webhook_url": "https://shop.vn/webhooks/monapay",
+    "auth_type": "HMAC_SHA256",
+    "secret_key": os.environ["MONA_WEBHOOK_SECRET"],
+    "payload_format": "application/json",
+})
+
+qr = mona.qr.generate({
+    "ownerNumber": "123456789", "ownerType": "ORG",
+    "merchantId": "MC00012345", "terminalId": "TM0001", "orderId": "DH10234",
+    "virtualAccountPrefix": "MONA", "beneficiaryName": "CONG TY ABC",
+    "amount": 2500000, "description": "Thanh toan DH10234",
+})
+print(qr["qr_data_url"])
+```
+
+Client tự login lại và thử request đúng một lần khi gặp HTTP 401. Các method trả trực tiếp trường `data`; `ApiError` có `status` và `body`.
+
+Các nhóm method: `keys`, `va`, `bank_accounts`, `qr`, `transactions`, `webhooks`, `webhook_logs`. Tên method dùng snake_case, ví dụ `va.register_notification(...)` và `transactions.retry(id, target_type="WEBHOOK", target_id=...)`.
+
+Đọc hết các trang giao dịch:
+
+```python
+for tx in mona.iter_transactions("MONA0000010234", limit=100):
+    print(tx["transaction_code"], tx["amount"])
+```
+
+## Xác thực webhook
+
+Luôn truyền đúng `request.body` dạng bytes, không parse rồi encode lại.
+
+```python
+from monapay import verify_webhook
+
+result = verify_webhook(raw_body, headers, os.environ["MONA_WEBHOOK_SECRET"])
+if not result.ok:
+    return {"reason": result.reason}, 401
+save_once(result.payload["transaction_code"], result.payload)
+```
+
+Ví dụ nhận webhook cho Flask, FastAPI và Django nằm trong `examples/`. Dùng `transaction_code` làm unique key để chống xử lý trùng.
+
+Tài liệu: https://monapay.vn/docs · AI/LLM: https://monapay.vn/llms.txt · Hotline 1900 636 648 · info@themona.global
+
+## Test
+
+Từ thư mục chứa `python/`:
+
+```bash
+python3 -m unittest discover python/tests
+```
+
+License MIT.

monapay-0.1.0/monapay.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+monapay/__init__.py
+monapay/client.py
+monapay/webhook.py
+monapay.egg-info/PKG-INFO
+monapay.egg-info/SOURCES.txt
+monapay.egg-info/dependency_links.txt
+monapay.egg-info/top_level.txt
+tests/test_client.py
+tests/test_webhook.py

monapay-0.1.0/monapay.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

monapay-0.1.0/monapay.egg-info/top_level.txt

@@ -0,0 +1 @@
+monapay

monapay-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "monapay"
+version = "0.1.0"
+description = "SDK Python zero-dependency cho MONA Pay"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "The MONA Group", email = "info@themona.global" }]
+keywords = ["monapay", "vietqr", "virtual-account", "payment", "webhook"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+]
+
+[project.urls]
+Documentation = "https://monapay.vn/docs"
+Repository = "https://github.com/monapay/monapay-python"
+
+[tool.setuptools.packages.find]
+include = ["monapay*"]

monapay-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

monapay-0.1.0/tests/test_client.py

@@ -0,0 +1,101 @@
+import io
+import json
+import pathlib
+import sys
+import unittest
+import urllib.error
+from unittest.mock import patch
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
+
+from monapay import MonaPay
+
+
+class FakeResponse:
+    def __init__(self, payload, status=200):
+        self.payload = json.dumps(payload).encode("utf-8")
+        self.status = status
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        return False
+
+    def read(self):
+        return self.payload
+
+    def getcode(self):
+        return self.status
+
+
+class ClientTests(unittest.TestCase):
+    @patch("urllib.request.urlopen")
+    def test_builds_url_headers_and_caches_token(self, urlopen):
+        urlopen.side_effect = [
+            FakeResponse({"success": True, "data": {"access_token": "token-1"}}),
+            FakeResponse({"success": True, "data": {"id": "hook-1"}}),
+            FakeResponse({"success": True, "data": {"username": "user"}}),
+        ]
+        client = MonaPay(
+            "user", "pass", client_secret="client-secret", base_url="https://example.test/"
+        )
+        client.webhooks.create({"name": "Shop", "webhook_url": "https://shop.test/hook"})
+        client.me()
+
+        login_request = urlopen.call_args_list[0].args[0]
+        write_request = urlopen.call_args_list[1].args[0]
+        read_request = urlopen.call_args_list[2].args[0]
+        self.assertEqual(login_request.full_url, "https://example.test/api/v1/client/login")
+        self.assertEqual(write_request.full_url, "https://example.test/api/v1/client-webhooks")
+        self.assertEqual(write_request.get_header("Authorization"), "Bearer token-1")
+        self.assertEqual(write_request.get_header("X-client-secret"), "client-secret")
+        self.assertIsNone(read_request.get_header("X-client-secret"))
+        self.assertEqual(urlopen.call_count, 3)
+
+    @patch("urllib.request.urlopen")
+    def test_refreshes_once_after_401(self, urlopen):
+        expired = urllib.error.HTTPError(
+            "https://example.test/api/v1/client/me",
+            401,
+            "Unauthorized",
+            {},
+            io.BytesIO(b'{"detail":"expired"}'),
+        )
+        urlopen.side_effect = [
+            FakeResponse({"success": True, "data": {"access_token": "token-1"}}),
+            expired,
+            FakeResponse({"success": True, "data": {"access_token": "token-2"}}),
+            FakeResponse({"success": True, "data": {"username": "user"}}),
+        ]
+        client = MonaPay("user", "pass", base_url="https://example.test")
+        self.assertEqual(client.me(), {"username": "user"})
+        final_request = urlopen.call_args_list[3].args[0]
+        self.assertEqual(final_request.get_header("Authorization"), "Bearer token-2")
+
+    @patch("urllib.request.urlopen")
+    def test_iter_transactions_reads_all_pages(self, urlopen):
+        urlopen.side_effect = [
+            FakeResponse({"success": True, "data": {"access_token": "token"}}),
+            FakeResponse(
+                {
+                    "success": True,
+                    "data": {"data": [{"id": "tx-1"}], "has_next": True, "last_page": 2},
+                }
+            ),
+            FakeResponse(
+                {
+                    "success": True,
+                    "data": {"data": [{"id": "tx-2"}], "has_next": False, "last_page": 2},
+                }
+            ),
+        ]
+        client = MonaPay("user", "pass", base_url="https://example.test")
+        items = list(client.iter_transactions("MONA 01", limit=1))
+        self.assertEqual([item["id"] for item in items], ["tx-1", "tx-2"])
+        self.assertIn("virtual_account_number=MONA+01", urlopen.call_args_list[1].args[0].full_url)
+        self.assertIn("page=2", urlopen.call_args_list[2].args[0].full_url)
+
+
+if __name__ == "__main__":
+    unittest.main()

monapay-0.1.0/tests/test_webhook.py

@@ -0,0 +1,64 @@
+import hashlib
+import hmac
+import json
+import pathlib
+import sys
+import time
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
+
+from monapay import verify_webhook
+
+
+class WebhookTests(unittest.TestCase):
+    def signature(self, raw_body, secret, timestamp):
+        digest = hmac.new(
+            secret.encode(), str(timestamp).encode() + b"." + raw_body, hashlib.sha256
+        ).hexdigest()
+        return "sha256=" + digest
+
+    def test_valid_signature(self):
+        raw = json.dumps({"amount": 2500000, "transaction_code": "FT1"}).encode()
+        timestamp = int(time.time())
+        result = verify_webhook(
+            raw,
+            {
+                "X-Mona-Timestamp": str(timestamp),
+                "x-mona-signature": self.signature(raw, "secret", timestamp),
+            },
+            "secret",
+        )
+        self.assertTrue(result.ok)
+        self.assertEqual(result.payload["transaction_code"], "FT1")
+
+    def test_invalid_signature(self):
+        timestamp = int(time.time())
+        result = verify_webhook(
+            b"{}",
+            {
+                "x-mona-timestamp": str(timestamp),
+                "x-mona-signature": "sha256=" + "0" * 64,
+            },
+            "secret",
+        )
+        self.assertFalse(result.ok)
+        self.assertEqual(result.reason, "invalid_signature")
+
+    def test_expired_timestamp(self):
+        timestamp = int(time.time()) - 301
+        result = verify_webhook(
+            b"{}",
+            {
+                "x-mona-timestamp": str(timestamp),
+                "x-mona-signature": self.signature(b"{}", "secret", timestamp),
+            },
+            "secret",
+            tolerance=300,
+        )
+        self.assertFalse(result.ok)
+        self.assertEqual(result.reason, "timestamp_out_of_tolerance")
+
+
+if __name__ == "__main__":
+    unittest.main()