Metadata-Version: 2.4
Name: monapay
Version: 0.5.1
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,email
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, Telegram và email, 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.

## Tạo link thu tiền

```python
from monapay import MonaPay
mona = MonaPay.from_env()
checkout = mona.checkouts.create({
    "amount": 250000, "order_code": "DH10234", "return_url": "https://shop.vn/payment/return",
})
print(checkout["checkout_url"])
```

## Cài đặt

```bash
pip install monapay
```

## Sử dụng

Các sub-client tương ứng toàn bộ API: `me`, `keys`, `bankAccounts`, `virtualAccounts`, `qr`, `transactions`, `webhooks`, `webhookLogs`, `emailConfigs`, `emailLogs`, `checkouts`, `paymentProfile`, `sandbox`. Trong Python, các nhóm dùng snake_case như `bank_accounts`, `webhook_logs`, `email_configs`, `email_logs`, `payment_profile`; factory tương đương `MonaPay.fromEnv()` của Node là `MonaPay.from_env()`.

Khởi tạo từ biến môi trường hoặc truyền credentials tường minh:

```python
import os
from monapay import MonaPay

mona = MonaPay.from_env()

mona_explicit = MonaPay(
    client_id=os.environ["MONAPAY_CLIENT_ID"],
    client_secret=os.environ["MONAPAY_CLIENT_SECRET"],
)

# Tự lấy OAuth token và cache tới gần hạn.
print(mona.me())

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"])
```

`MonaPay.from_env()` ưu tiên `MONAPAY_CLIENT_ID` + `MONAPAY_CLIENT_SECRET`. Cách cũ `MonaPay(username, password)` hoặc `MONAPAY_USERNAME` + `MONAPAY_PASSWORD` vẫn được hỗ trợ, nhưng tài khoản bật 2FA không login bằng mật khẩu được. Client cache token theo `expires_in` (làm mới sớm 60 giây) 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 dùng snake_case; alias `paymentProfile` có sẵn khi anh chị muốn giữ cùng tên với Node SDK.

| Sub-client | Method |
| --- | --- |
| `keys`, `bank_accounts` | `generate/list/destroy`, `list` |
| `va` | `register/verify/register_notification/verify_notification/notification_detail/list` |
| `payment_profile`, `checkouts` | `get/set`, `create/get/list/cancel` |
| `qr` | `generate/cancel` |
| `transactions` | `list/iterate/retry` |
| `sandbox` | `transaction` |
| `webhooks`, `webhook_logs` | `list/create/update/remove/test`, `list/stats` |
| `email_configs`, `email_logs`, `email_suppressions` | `list/get/create/update/remove/verify/resend_verification/test`, `list/stats`, `list/remove` |

## Thử bằng sandbox (không cần nối ngân hàng)

```python
checkout = mona.checkouts.create({
    "amount": 10000, "order_code": "DH10234",
    "return_url": "https://shop.vn/payment/return",
}, sandbox=True)
mona.sandbox.transaction(
    virtual_account_number=checkout["bank"]["account_number"],
    amount=checkout["amount"], description=checkout["order_code"],
)
paid = mona.checkouts.get(checkout["id"])
print(paid["status"])  # "paid"
```

Webhook `CHECKOUT_PAID` có trường `checkout_id`, không phải `id` (tương ứng `event.checkout_id` trên object); với dict Python, dùng `event["checkout_id"]`.

## Nối ngân hàng bằng OTP (4 bước)

OTP do ACB gửi về số điện thoại đăng ký của chủ tài khoản. Ứng dụng phải hỏi người dùng ở bước 2 và 4, không tự tạo hoặc lưu OTP.

```python
registration = mona.register_virtual_account({
    "customer_type": "PERS",
    "account_number": 123456789,
    "phone_number": "0901234567",
    "virtual_account_info": {
        "virtual_account_prefix_code": "LOC",
        "virtual_account_content": "DH10234",
        "virtual_account_explain": "Don hang 10234",
    },
    "user_agreement": True,
})

va = mona.verify_virtual_account(registration["acb_request"]["id"], otp_nguoi_dung_nhap)
notification = mona.register_notification(va["id"])
mona.verify_notification(notification["acb_request"]["id"], otp_lan_hai)

print(mona.notification_detail(va["id"]))
```

## Thông báo qua email

MONA Pay gửi mã 6 số tới từng địa chỉ mới. Ứng dụng phải hỏi người dùng mã trong hộp thư rồi xác minh, không tự đoán mã.

```python
config = mona.email_configs.create({"name": "Kế toán", "recipients": ["kt@shop.vn"]})
email = config["pending_verification"][0]
code = ask_user_for_code(email)
mona.email_configs.verify(config["id"], email, code)
mona.email_configs.test(config["id"])
print(mona.email_logs.list(config_id=config["id"], status="sent"))
```

Địa chỉ bounce hoặc khiếu nại nằm trong `email_suppressions.list()`; chỉ gọi `email_suppressions.remove(email)` sau khi đã sửa nguyên nhân.

Đọ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 gói:

```bash
python -m pytest tests
```

License MIT.
