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.
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"])pip install monapayCá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:
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 |
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"].
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.
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"]))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ã.
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:
for tx in mona.iter_transactions("MONA0000010234", limit=100):
print(tx["transaction_code"], tx["amount"])Luôn truyền đúng request.body dạng bytes, không parse rồi encode lại.
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
Từ thư mục gói:
python -m pytest testsLicense MIT.