monapay-mcp

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:

Biến	Bắt buộc	Ý nghĩa
MONAPAY_CLIENT_ID	có (khuyến nghị)	client_id của API key tạo trong dashboard
MONAPAY_CLIENT_SECRET	có (khuyến nghị)	client_secret hiện một lần; dùng lấy OAuth token và ký quyền cho lệnh ghi
MONAPAY_USERNAME	cách cũ	tên đăng nhập MONA Pay; chỉ dùng khi không có client credentials
MONAPAY_PASSWORD	cách cũ	mật khẩu; tài khoản bật 2FA không dùng được cách này
MONAPAY_BASE_URL	không	mặc định https://api.monapay.vn

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

Tool	Làm gì
monapay_whoami	kiểm tra kết nối, đếm bank/VA và gợi ý kênh thông báo tiếp theo
monapay_me	hồ sơ tài khoản đang đăng nhập
monapay_link_bank_start · monapay_link_bank_verify_otp	nối tài khoản ACB và tạo VA bằng OTP lần 1
monapay_notification_register · monapay_notification_verify_otp	bật thông báo tiền vào bằng OTP lần 2
monapay_list_bank_accounts · monapay_list_virtual_accounts	tài khoản ngân hàng đã nối, tài khoản ảo (VA)
monapay_get_payment_profile · monapay_set_payment_profile	xem hoặc thiết lập hồ sơ dùng cho trang thanh toán
monapay_create_checkout · monapay_get_checkout · monapay_list_checkouts · monapay_cancel_checkout	tạo link thu tiền, kiểm tra, lọc và huỷ phiên thanh toán
monapay_create_qr · monapay_cancel_qr	tạo / huỷ VietQR động cho đơn hàng
monapay_list_transactions	tra giao dịch tiền vào theo VA (đối soát)
monapay_list_webhooks · monapay_create_webhook · monapay_update_webhook · monapay_delete_webhook	cấu hình webhook (HMAC-SHA256 khuyến nghị)
monapay_test_webhook · monapay_webhook_logs · monapay_webhook_stats	bắn thử, lịch sử từng lần gửi, tỷ lệ thành công / P95
monapay_sandbox_transaction	Tạo giao dịch tiền vào giả cho VA đã nối (webhook/Telegram/email/Zalo chạy như thật, không tính hạn mức).
monapay_list_email_configs · monapay_create_email_config · monapay_update_email_config · monapay_delete_email_config	cấu hình email cho tối đa 10 người nhận
monapay_verify_email · monapay_resend_email_verification · monapay_test_email	xác minh bằng mã 6 số, gửi lại mã và gửi email thử
monapay_email_logs · monapay_email_stats	lịch sử meta, tỷ lệ thành công / P95 và nhóm lỗi gửi email
monapay_list_email_suppressions · monapay_remove_email_suppression	xem và gỡ địa chỉ bị chặn gửi
monapay_list_zalo_groups · monapay_create_zalo_group · monapay_update_zalo_group · monapay_delete_zalo_group	xem và cấu hình thông báo vào nhóm Zalo
monapay_test_zalo_group · monapay_zalo_group_logs	gửi thử và tra lịch sử gửi nhóm Zalo
monapay_retry_transaction	gửi lại webhook hoặc Telegram cho một giao dịch
monapay_generate_key	sinh client_secret mới
monapay_rotate_key	xoay secret của key hiện tại khi nghi bị lộ; sau đó phải cập nhật MONAPAY_CLIENT_SECRET
monapay_verify_signature	kiểm chữ ký webhook ngay tại chỗ, không gọi mạng
monapay_generate_webhook_snippet	code mẫu endpoint nhận webhook PHP / Node / Python đúng chuẩn

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.

• 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.
• Hỏi người dùng OTP rồi gọi monapay_link_bank_verify_otp. Tool trả virtual_account_id và số VA.
• Gọi monapay_notification_register với virtual_account_id; ACB gửi OTP lần 2.
• 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 [phone] · [e-mail]