Gói và hoá đơn (billing)
MONA Pay miễn phí 500 giao dịch tiền vào mỗi tháng, đủ mọi tính năng. Bán nhiều hơn thì nâng gói trả phí tính theo số giao dịch, không thu phần trăm trên số tiền. Trang này dành cho lập trình viên và AI agent cần đọc gói, đọc mức dùng và nâng gói bằng API thay vì bấm dashboard. Giá niêm yết ở trang bảng giá.
Khách hàng của MONA: miễn phí hoàn toàn
Anh chị đang dùng dịch vụ web, phần mềm hay hosting của The MONA Group thì có gói riêng mona: miễn phí hoàn toàn, không giới hạn giao dịch, trong suốt thời gian còn là khách hàng của MONA. Gói này không mua qua API được, đội MONA gán khi bàn giao dự án hoặc anh chị gọi 1900 636 648. Đã được gán thì GET /api/v1/billing/usage trả plan_code: "mona" và mọi phần dưới đây về hạn mức không còn liên quan tới anh chị.
Cách đếm giao dịch
Giao dịch = 1 khoản tiền vào (credit) ghi nhận trên mọi tài khoản và tài khoản ảo đã nối, cắt tháng theo giờ Việt Nam (UTC+7). Tiền ra, giao dịch sandbox và webhook gửi lại không tính.
Vượt hạn mức thì sao:
- Gói Miễn phí: tháng đầu tiên vượt vẫn báo đủ (du di). Từ tháng vượt kế tiếp, giao dịch vượt mức vẫn ghi nhận trong dashboard nhưng ngưng gửi webhook và Telegram cho tới khi nâng gói. Không mất giao dịch. Nếu client có cấu hình webhook, mỗi giao dịch bị chặn ghi một dòng
webhook_logvới lỗiQUOTA_EXCEEDEDđể đối chiếu. - Gói trả phí: không khoá, phần vượt tính phụ trội theo từng giao dịch (niêm yết theo gói), gom vào hoá đơn cuối tháng.
- Hệ nhắc qua Telegram đúng một lần ở mốc 80% và 100% hạn mức trong tháng.
Các endpoint
Base URL https://api.monapay.vn (alias cũ https://ipn.mona.host). Xác thực Bearer như mọi API khác, xem Xác thực. Request ghi (POST) cần thêm header X-Client-Secret.
| Method | Đường dẫn | Quyền | Dùng để |
|---|---|---|---|
| GET | /api/v1/billing/plans |
Public | Đọc 5 gói: code, price_month, price_year (trả năm = 10 tháng), tx_limit, overage_per_tx, features |
| GET | /api/v1/billing/usage |
Bearer | Mức dùng tháng hiện tại: plan_code, tx_used, tx_limit, overage_tx, overage_amount, plan_expires_at |
| GET | /api/v1/billing/invoices |
Bearer | Danh sách hoá đơn, lọc ?status=, phân trang ?page=&limit=, trả { data, total } |
| POST | /api/v1/billing/invoices |
Bearer + secret | Tạo hoá đơn nâng gói, trả 201 |
| GET | /api/v1/billing/invoices/{id} |
Bearer | Chi tiết một hoá đơn, dùng để poll trạng thái |
| POST | /api/v1/billing/invoices/{id}/cancel |
Bearer + secret | Huỷ hoá đơn còn pending |
Nâng gói bằng API, từng bước
- Tạo hoá đơn:
curl -X POST https://api.monapay.vn/api/v1/billing/invoices \
-H "Authorization: Bearer $TOKEN" -H "X-Client-Secret: $SECRET" \
-H "Content-Type: application/json" \
-d '{"plan_code": "startup", "cycle": "month"}'plan_code nhận startup, business, enterprise, scale; cycle nhận month hoặc year (năm chỉ tính 10 tháng tiền).
-
Response 201 trả hoá đơn
status: "pending"với mã chuyển khoản dạngMPAY+ 6 số, hạn thanh toán 48 giờ, kèm khốipayment: link ảnh VietQR và payload EMVCo để tự dựng QR. Cho khách quét QR hoặc chuyển khoản đúng số tiền, nội dung ghi đúng mã MPAY vào tài khoản ghi trên hoá đơn. -
Tiền vào là hệ tự khớp trong vài giây (đọc thông báo giao dịch từ ngân hàng, so mã + số tiền). Poll
GET /api/v1/billing/invoices/{id}tới khistatusthànhpaid; gói kích hoạt ngay lúc đó. Cùng gói còn hạn thì cộng dồn từ ngày hết hạn cũ, đổi gói khác thì tính lại từ thời điểm thanh toán. -
Tạo nhầm thì
POST /api/v1/billing/invoices/{id}/cancelkhi còn pending; quá 48 giờ chưa trả, hoá đơn tự chuyểnexpired, không phát sinh gì.
Không muốn đụng API: dashboard my.monapay.vn → Gói và thanh toán, cùng một luồng, có sẵn panel QR tự đổi trạng thái khi nhận tiền.
Câu hỏi thường gặp
Đang gói Miễn phí, chưa từng vượt, có bị trừ gì không? Không. Không phí mở tài khoản, không phí duy trì, không thu phần trăm trên số tiền. Chỉ khi bán vượt 500 giao dịch/tháng mới cần cân nhắc nâng gói.
Hoá đơn phụ trội tính lúc nào? Đầu tháng kế tiếp, hệ chốt kỳ tháng trước: gói trả phí có phần vượt sẽ nhận một hoá đơn phụ trội (mỗi kỳ đúng một hoá đơn). Gói trả phí quá hạn 7 ngày chưa gia hạn thì hạ về Miễn phí, dữ liệu giữ nguyên.
Webhook có đổi gì khi nâng gói không? Không. Payload, chữ ký HMAC, cấu hình webhook giữ nguyên; gói chỉ quyết định hạn mức số giao dịch được fan-out mỗi tháng.