monapay-mcp — MCP server cho MONA Pay

MONA Pay là API ngân hàng và dịch vụ xác nhận thanh toán tự độ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, email và nhóm Zalo, thiết kế để cả lập trình viên lẫn AI agent tích hợp trong vài phút. Miễn phí hoàn toàn, tiền không đi qua MONA Pay.

monapay-mcp cho Claude Code, Cursor, Codex (hoặc bất kỳ client MCP nào) gọi thẳng MONA Pay ngay trong lúc code: tạo VietQR cho đơn, tra giao dịch, cấu hình và bắn thử webhook, kiểm chữ ký HMAC, lấy code mẫu nhận webhook.

Cài đặt

Cần Node ≥ 18 và một tài khoản MONA Pay (đăng ký xong dùng ngay): https://my.monapay.vn/auth?mode=register

npx monapay-mcp   # chạy server qua stdio

Biến môi trường:

Claude Code

claude mcp add monapay \
  -e MONAPAY_CLIENT_ID=client_id_cua_anh_chi \
  -e MONAPAY_CLIENT_SECRET=client_secret_cua_anh_chi \
  -- npx -y monapay-mcp

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "monapay": {
      "command": "npx",
      "args": ["-y", "monapay-mcp"],
      "env": { "MONAPAY_CLIENT_ID": "client_id", "MONAPAY_CLIENT_SECRET": "client_secret" }
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.monapay]
command = "npx"
args = ["-y", "monapay-mcp"]
env = { MONAPAY_CLIENT_ID = "client_id", MONAPAY_CLIENT_SECRET = "client_secret" }

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "monapay": {
      "command": "npx",
      "args": ["-y", "monapay-mcp"],
      "env": { "MONAPAY_CLIENT_ID": "client_id", "MONAPAY_CLIENT_SECRET": "client_secret" }
    }
  }
}

Cách cũ: username/password

Nếu chưa tạo API key, có thể đặt MONAPAY_USERNAME và MONAPAY_PASSWORD. Nên chuyển sang client_id/client_secret; tài khoản bật 2FA không login bằng mật khẩu được.

Tool

Resource: monapay://docs/llms (mục lục tài liệu máy đọc), monapay://docs/{slug} (một trang docs dạng markdown, ví dụ monapay://docs/webhooks/tich-hop-webhook). Prompt: integrate-monapay (6 bước để agent tự tích hợp).

monapay_rotate_key dùng X-Client-Secret hiện tại để xoay đúng key khớp với MONAPAY_CLIENT_ID. Secret cũ hết hiệu lực ngay; hãy thay MONAPAY_CLIENT_SECRET trong cấu hình MCP và khởi động lại plugin/agent.

Ví dụ hội thoại

"Tích hợp nhận tiền chuyển khoản cho web Laravel này bằng MONA Pay."

Agent sẽ: gọi monapay_me → lấy code mẫu bằng monapay_generate_webhook_snippet(language="php") → viết endpoint vào dự án → monapay_create_webhook(auth_type="HMAC_SHA256", secret_key=...) → monapay_test_webhook → đọc monapay_webhook_logs để chắc endpoint trả 200 → dùng monapay_create_checkout cho từng đơn và đợi CHECKOUT_PAID.

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. Agent phải hỏi người dùng ở bước 2 và bước 4, tuyệt đối không tự đoán OTP.

1. Gọi monapay_link_bank_start với số tài khoản ACB, số điện thoại, loại khách hàng, prefix VA và mã định danh. Tool trả acb_request_id; ACB gửi OTP lần 1.
2. Hỏi người dùng OTP rồi gọi monapay_link_bank_verify_otp. Tool trả virtual_account_id và số VA.
3. Gọi monapay_notification_register với virtual_account_id; ACB gửi OTP lần 2.
4. Hỏi người dùng OTP lần 2 rồi gọi monapay_notification_verify_otp. Từ đây tiền vào sẽ được MONA Pay chuyển tiếp qua webhook đã cấu hình.

Nếu OTP sai hoặc hết hạn, gọi lại bước trước để ACB gửi mã mới.

Thông báo nhóm Zalo

Nhóm của khách phải có bot Gấu Mona do MONA thêm vào. group_id gồm 10–25 chữ số: khách hàng MONA lấy trong MONA Account/PMS tại dự án → kết nối Zalo → chatId, hoặc nhờ đội MONA tra theo tên nhóm. Người dùng chưa phải khách MONA chưa thể tự thêm bot; liên hệ MONA qua 1900 636 648 để nối nhóm Zalo.

Gọi monapay_create_zalo_group với group_id, tên dễ nhớ và các sự kiện cần nhận: TRANSACTION_IN, CHECKOUT_PAID, WEBHOOK_FAILED, VA_CREATED. Có thể giới hạn theo virtual_account_id, gửi thử bằng monapay_test_zalo_group, rồi kiểm tra bằng monapay_zalo_group_logs.

Zalo không parse Markdown. message_template phải là text thuần và hỗ trợ các biến {amount}, {description}, {virtual_account_number}, {transaction_code}, {transfer_date}; dạng {{amount}} cũng được hỗ trợ.

Chữ ký webhook

X-Mona-Signature: sha256=<hex> với hex = HMAC-SHA256(secret, "<X-Mona-Timestamp>.<raw_body>"), từ chối nếu timestamp lệch quá 300 giây, so sánh constant-time. transaction_code không đổi qua mọi lần gửi lại, dùng làm khoá chống trùng. Chi tiết: https://monapay.vn/docs/webhooks/bao-mat

Phát triển

npm install && npm test        # build + node --test
MONAPAY_CLIENT_ID=... MONAPAY_CLIENT_SECRET=... npm run smoke   # gọi thật vài tool GET

Tài liệu: https://monapay.vn/docs · llms.txt: https://monapay.vn/llms.txt · OpenAPI: https://monapay.vn/openapi.json · Hotline 1900 636 648 · info@themona.global