Skip to main content
Glama

monapay-mcp

An MCP server that lets AI coding agents such as Claude Code, Cursor and Codex (or any MCP client) work with MONA Pay while coding: link a bank account, create checkout links and VietQR codes, look up incoming transfers, configure and test webhooks, email and Zalo group notifications, and verify webhook signatures.

test

Published on npm as monapay-mcp and in the MCP Registry as vn.monapay/monapay-mcp.

Install

Requires Node.js 18 or later and a MONA Pay API key (client ID and client secret, created in the MONA Pay dashboard).

npx -y monapay-mcp   # starts the server over stdio

Claude Code

claude mcp add monapay \
  -e MONAPAY_CLIENT_ID=your_client_id \
  -e MONAPAY_CLIENT_SECRET=your_client_secret \
  -- npx -y monapay-mcp

Cursor (.cursor/mcp.json) and 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" }
    }
  }
}

Codex (~/.codex/config.toml)

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

Related MCP server: monapay-mcp

Configuration

Variable

Required

Meaning

MONAPAY_CLIENT_ID

yes (recommended)

client_id of an API key created in the dashboard

MONAPAY_CLIENT_SECRET

yes (recommended)

client_secret, shown once; used to obtain the OAuth token and authorize write actions

MONAPAY_USERNAME

legacy

MONA Pay username, used only when client credentials are not set

MONAPAY_PASSWORD

legacy

Password; does not work for accounts with 2FA enabled

MONAPAY_BASE_URL

no

Defaults to https://api.monapay.vn

Client credentials are recommended over username/password, because accounts with 2FA enabled cannot log in with a password.

Usage

Tools

Tool

What it does

monapay_quickstart

Entry point: checks account state (bank/VA linked, webhook configured) and returns the next steps

monapay_whoami

Verifies the connection and returns the account name and plan

monapay_me

Profile of the logged-in account

monapay_link_bank_start · monapay_link_bank_verify_otp

Link an ACB account and create a virtual account (first OTP)

monapay_notification_register · monapay_notification_verify_otp

Turn on incoming-transfer notifications (second OTP)

monapay_list_bank_accounts · monapay_list_virtual_accounts

Linked bank accounts and their virtual accounts (VA)

monapay_get_payment_profile · monapay_set_payment_profile

View or set the profile used by the hosted checkout page

monapay_create_checkout · monapay_get_checkout · monapay_list_checkouts · monapay_cancel_checkout

Create, inspect, filter and cancel hosted checkout sessions

monapay_create_qr · monapay_cancel_qr

Create or cancel a dynamic VietQR for an order

monapay_list_transactions

Incoming transactions for a VA (up to 100 per page), for reconciliation

monapay_get_transaction

Find one incoming transaction by transaction_code or ID within a VA

monapay_get_transactions_summary

Incoming totals, transaction count and daily data for a date range

monapay_sandbox_transaction

Create a fake incoming transaction; webhooks, Telegram, email and Zalo fire as for a real one. Without a VA, a sandbox VA is issued

monapay_list_webhooks · monapay_create_webhook · monapay_update_webhook · monapay_delete_webhook

Webhook configs (NONE, API_KEY or HMAC_SHA256; HMAC recommended)

monapay_test_webhook · monapay_webhook_logs · monapay_webhook_stats

Send a dummy webhook, per-delivery history, success rate / P95

monapay_list_email_configs · monapay_create_email_config · monapay_update_email_config · monapay_delete_email_config

Email notification configs with 1 to 10 recipients

monapay_verify_email · monapay_resend_email_verification · monapay_test_email

Verify a recipient with a 6-digit code, resend the code, send a test email

monapay_email_logs · monapay_email_stats

Delivery metadata, success rate / P95 and error groups

monapay_list_email_suppressions · monapay_remove_email_suppression

View and remove suppressed addresses

monapay_list_zalo_groups · monapay_create_zalo_group · monapay_update_zalo_group · monapay_delete_zalo_group

Zalo group notification configs

monapay_test_zalo_group · monapay_zalo_group_logs

Send a test message and read Zalo group delivery history

monapay_retry_transaction

Re-send the webhook or Telegram notification for a transaction

monapay_generate_key

Generate a new client_secret

monapay_rotate_key

Rotate the secret of the current key when it may be exposed

monapay_verify_signature

Verify a webhook signature locally, with no network call

monapay_generate_webhook_snippet

Webhook receiver code for PHP, Node or Python, with a sample payload

Resources and prompt

  • monapay://docs/llms: machine-readable index of the MONA Pay docs.

  • monapay://docs/{slug}: one docs page as Markdown, for example monapay://docs/webhooks/tich-hop-webhook.

  • Prompt integrate-monapay (arguments language, framework): a 6-step plan for the agent to integrate MONA Pay into the current project.

Example

"Integrate automatic bank transfer confirmation into this Laravel site with MONA Pay."

The agent calls monapay_whoami, gets receiver code with monapay_generate_webhook_snippet(language="php"), writes the endpoint into the project, registers it with monapay_create_webhook(auth_type="HMAC_SHA256", secret_key=...), fires monapay_test_webhook, reads monapay_webhook_logs to confirm the endpoint returns 200, then uses monapay_create_checkout for each order and waits for CHECKOUT_PAID.

ACB sends each OTP to the account holder's registered phone. The agent must ask the user at steps 2 and 4 and never guess an OTP.

  1. Call monapay_link_bank_start with the ACB account number, phone number, customer type, VA prefix and identifier. It returns acb_request_id, and ACB sends the first OTP.

  2. Ask the user for the OTP and call monapay_link_bank_verify_otp. It returns virtual_account_id and the VA number.

  3. Call monapay_notification_register with virtual_account_id. ACB sends the second OTP.

  4. Ask the user for the second OTP and call monapay_notification_verify_otp. Incoming transfers are now forwarded to your configured webhooks.

If an OTP is wrong or expired, call the previous step again to get a new code.

Zalo group notifications

The group must contain the MONA bot (Gấu Mona), which is added by the MONA team. group_id is 10 to 25 digits and comes from MONA Account/PMS.

Call monapay_create_zalo_group with group_id, a friendly name and the events to receive: TRANSACTION_IN, CHECKOUT_PAID, WEBHOOK_FAILED, VA_CREATED. You can limit it to one virtual_account_id, send a test with monapay_test_zalo_group and check delivery with monapay_zalo_group_logs.

Zalo does not render Markdown, so message_template must be plain text. It supports {amount}, {description}, {virtual_account_number}, {transaction_code} and {transfer_date}; the {{amount}} form also works.

Key rotation

monapay_rotate_key uses the current secret to rotate the key that matches MONAPAY_CLIENT_ID. The old secret stops working immediately; update MONAPAY_CLIENT_SECRET in your MCP config and restart the client.

Webhook signature

X-Mona-Signature: sha256=<hex>, where hex = HMAC-SHA256(secret, "<X-Mona-Timestamp>.<raw_body>"). Reject requests whose timestamp is more than 300 seconds off and compare in constant time. transaction_code stays the same across retries, so use it as the deduplication key.

Development

npm install
npm test     # build + node --test

# Calls a few read-only tools against a real account
MONAPAY_CLIENT_ID=... MONAPAY_CLIENT_SECRET=... MONAPAY_BASE_URL=https://api.monapay.vn npm run smoke

Agent guide: https://monapay.vn/ai-agent · Documentation: https://monapay.vn/docs

License

MIT

MONA Pay is part of MONA Cloud by The MONA Group.

Available Tools

50 tools
monapay_cancel_checkoutHuỷ phiên thanh toánA

Huỷ checkout đang pending; checkout đã paid, expired hoặc cancelled không thể huỷ lại. / Cancel a pending checkout.

Inputs: checkout_id (required), idempotency_key.

monapay_cancel_qrHuỷ mã QRB

Huỷ một mã VietQR động đã tạo. / Cancel a dynamic QR.

Inputs: qr_code_id (required).

monapay_create_checkoutTạo link thu tiềnB

Tạo link thu tiền, đưa link cho khách hoặc chuyển hướng checkout; đợi webhook CHECKOUT_PAID trước khi giao hàng. / Create a hosted checkout link; wait for CHECKOUT_PAID before fulfilment.

Inputs: amount (required), order_code (required), return_url (required), sandbox, +8 more.

monapay_create_email_configTạo cấu hình thông báo emailA

Tạo kênh thông báo email. Sau khi tạo, MONA Pay gửi mã 6 số tới từng địa chỉ; hỏi người dùng mã rồi gọi monapay_verify_email; không tự đoán mã. / Create an email notification config. MONA Pay sends a 6-digit code to each address; ask the user for each code, call monapay_verify_email, and never guess a code.

Inputs: name (required), recipients (required), events, virtual_account_id.

monapay_create_qrTạo VietQR động cho đơn hàngA

Tạo mã VietQR động điền sẵn số tiền + nội dung cho một đơn hàng qua ACB. Khách quét là tiền vào tài khoản ảo, MONA Pay bắn webhook. / Create a dynamic VietQR for an order.

Inputs: amount (required), orderId (required), merchantId (required), ownerNumber (required), +9 more.

monapay_create_webhookTạo cấu hình webhookC

Đăng ký URL nhận webhook khi có tiền vào; khuyến nghị auth_type HMAC_SHA256 + secret_key. / Create a webhook config.

Inputs: name (required), webhook_url (required), auth_type, secret_key, +3 more.

monapay_create_zalo_groupNối nhóm ZaloA

Nối nhóm có bot Gấu Mona bằng group_id 10–25 chữ số lấy từ MONA Account/PMS; Zalo không parse Markdown, nên template phải là text thuần.

Inputs: group_id (required), friendly_name (required), events, is_active, +2 more.

monapay_delete_email_configXoá cấu hình thông báo emailA

Xoá vĩnh viễn một cấu hình email. / Permanently delete an email notification config.

Inputs: config_id (required).

monapay_delete_webhookXoá cấu hình webhookC

Xoá một webhook config. / Delete a webhook config.

Inputs: config_id (required).

monapay_delete_zalo_groupXoá nhóm ZaloB

Xoá một cấu hình thông báo nhóm Zalo.

Inputs: id (required).

monapay_email_logsLịch sử gửi emailA

Tra meta từng lần gửi email, không chứa nội dung thư; lọc theo cấu hình, trạng thái, sự kiện và ngày. / List email delivery metadata; message bodies are never stored.

Inputs: page, limit, status, to_date, +3 more.

monapay_email_statsThống kê gửi emailB

Lấy tổng số gửi, tỷ lệ thành công, P95 và nhóm lỗi trong khoảng ngày. / Get email delivery totals, success rate, P95 latency and error groups.

Inputs: to_date, from_date.

monapay_generate_keyTạo API key (client_secret)B

Sinh client_secret mới (hiện 1 lần) để dùng header X-Client-Secret. / Generate a client secret.

Inputs: name.

monapay_generate_webhook_snippetCode mẫu nhận webhookA

Trả code mẫu endpoint nhận webhook MONA Pay + verify HMAC đúng chuẩn cho PHP / Node / Python, kèm payload mẫu. / Get a webhook receiver snippet.

Inputs: language (required).

monapay_get_checkoutLấy một phiên thanh toánA

Lấy trạng thái và chi tiết checkout theo ID; nên kiểm tra server-side trước khi giao hàng. / Get a checkout by ID.

Inputs: checkout_id (required).

monapay_get_payment_profileLấy hồ sơ trang thanh toánA

Lấy tên shop, nhận diện và tài khoản mặc định dùng cho trang thanh toán. / Get the hosted-checkout payment profile.

Inputs: no named parameters.

monapay_get_transactionTra 1 giao dich theo ma don hoac IDA

Tim 1 giao dich tien vao theo transaction_code (ma don, vd DH10234) hoac id trong mot tai khoan ao; dung de kiem "don X da thanh toan chua". / Get one incoming transaction by code/id within a virtual account.

Inputs: id_or_code (required), virtual_account_number (required).

monapay_get_transactions_summaryTong tien vao theo khoang (KHONG phai so du vi)A

Tong tien vao + so giao dich + du lieu theo ngay trong khoang chon. LUU Y: MONA Pay KHONG giu tien, khong co "so du vi"; day la tong tien da vao tai khoan ngan hang cua ban. / Incoming totals over a date range (MONA Pay holds no wallet balance).

Inputs: end_date, start_date.

monapay_list_bank_accountsDanh sách tài khoản ngân hàng đã nốiA

Liệt kê tài khoản ngân hàng (ACB…) đã nối vào MONA Pay. / List linked bank accounts.

Inputs: no named parameters.

monapay_list_checkoutsDanh sách phiên thanh toánB

Liệt kê checkout theo trạng thái, mã đơn, khoảng ngày và phân trang. / List and filter hosted checkouts.

Inputs: page, limit, status, to_date, +2 more.

monapay_list_email_configsDanh sách cấu hình emailA

Liệt kê các cấu hình gửi thông báo email và trạng thái xác minh người nhận. / List email notification configs and recipient verification status.

Inputs: no named parameters.

monapay_list_email_suppressionsDanh sách email bị chặn gửiB

Liệt kê địa chỉ bị suppression do bounce, khiếu nại hoặc tắt tay. / List suppressed recipient addresses.

Inputs: no named parameters.

monapay_list_transactionsTra giao dịch tiền vàoB

Liệt kê giao dịch tiền vào theo tài khoản ảo, phân trang tối đa 100/trang; dùng để đối soát. / List incoming transactions.

Inputs: virtual_account_number (required), page, limit.

monapay_list_virtual_accountsDanh sách tài khoản ảo (VA)A

Liệt kê tài khoản ảo thuộc một tài khoản ngân hàng. / List virtual accounts of a bank account.

Inputs: bank_account_id (required).

monapay_list_webhooksDanh sách cấu hình webhookA

Liệt kê webhook đã cấu hình. / List webhook configs.

Inputs: no named parameters.

monapay_list_zalo_groupsDanh sách nhóm ZaloA

Liệt kê cấu hình thông báo nhóm Zalo; nhóm phải có bot Gấu Mona.

Inputs: no named parameters.

monapay_meHồ sơ tài khoản MONA PayA

Lấy thông tin tài khoản MONA Pay đang đăng nhập (id, tên, trạng thái). / Get current MONA Pay client profile.

Inputs: no named parameters.

monapay_notification_registerĐăng ký thông báo tiền vào và gửi OTP lần 2A

Bước 3/4: đăng ký nhận thông báo giao dịch tức thì. OTP lần 2 do ngân hàng gửi về điện thoại của người dùng; agent phải HỎI người dùng rồi mới gọi tool xác thực, không được tự đoán. / Step 3/4: register real-time transaction notifications. The second OTP is sent by the bank to the user’s phone; the agent MUST ASK the user before verification and must never guess it.

Inputs: virtual_account_id (required).

monapay_notification_verify_otpXác thực OTP lần 2 và hoàn tất nhận tiềnA

Bước 4/4: OTP do ngân hàng gửi về điện thoại của người dùng, agent phải HỎI người dùng rồi mới gọi tool này; tuyệt đối không tự đoán OTP. / Step 4/4: the OTP is sent by the bank to the user’s phone; the agent MUST ASK the user before calling this tool and must never guess the OTP.

Inputs: code (required), acb_request_id (required).

monapay_quickstartBat dau nhan tien: kiem tra trang thai va cac buoc tiep theoA

DIEM VAO cho y dinh "toi muon nhan tien chuyen khoan tu dong". Goi tool nay TRUOC: no kiem tra tai khoan (da noi ngan hang/VA chua, da co webhook chua) va tra ve cac BUOC TIEP THEO cu the + recipe end-to-end. / Entry point for "I want to receive bank transfers": checks state and returns concrete next steps + recipe.

Inputs: no named parameters.

monapay_remove_email_suppressionGỡ chặn gửi tới một emailA

Gỡ suppression sau khi đã sửa nguyên nhân; client tự chịu trách nhiệm khi gửi lại. / Remove a suppression after fixing its cause; the client accepts responsibility for future sends.

Inputs: email (required).

monapay_resend_email_verificationGửi lại mã xác minh emailB

Gửi mã xác minh mới tới một địa chỉ trong cấu hình; giới hạn 5 lần/địa chỉ/giờ. / Resend a verification code, limited to five requests per address per hour.

Inputs: email (required), config_id (required).

monapay_retry_transactionGửi lại thông báo của một giao dịchB

Gửi lại webhook hoặc Telegram cho giao dịch đã có. / Re-send webhook/Telegram for a transaction.

Inputs: transaction_id (required), target_id, target_type.

monapay_rotate_keyXoay secret API key hiện tạiA

Dùng khi secret nghi lộ; xoay key hiện tại bằng X-Client-Secret. Sau khi xoay phải cập nhật MONAPAY_CLIENT_SECRET ở plugin/agent rồi khởi động lại. / Rotate the current API key secret after suspected exposure, then update MONAPAY_CLIENT_SECRET.

Inputs: no named parameters.

monapay_sandbox_transactionTạo giao dịch thử (sandbox, không tốn tiền)A

Tạo một giao dịch tiền vào GIẢ: chưa nối ngân hàng thì MONA Pay tự cấp VA sandbox SBX; MONA Pay ghi giao dịch, bắn webhook có chữ ký, gửi Telegram/email/Zalo, khớp checkout như tiền thật, không tính hạn mức. / Create a fake incoming transaction in the sandbox.

Inputs: amount, description, virtual_account_number.

monapay_set_payment_profileThiết lập hồ sơ trang thanh toánB

Tạo hoặc cập nhật tên shop, nhận diện và tài khoản nhận tiền mặc định trước khi tạo checkout. Secret ký redirect chỉ được API trả một lần. / Create or update the hosted-checkout payment profile.

Inputs: locale, hotline, logo_url, va_prefix, +11 more.

monapay_test_emailGửi thử thông báo emailA

Gửi email mẫu tới các địa chỉ đã xác minh trong cấu hình. / Send a test notification to verified recipients in a config.

Inputs: config_id (required).

monapay_test_webhookBắn webhook thửB

MONA Pay gửi một giao dịch giả (is_dummy) tới URL để kiểm tra endpoint + chữ ký. / Send a dummy webhook.

Inputs: auth_type, secret_key, webhook_url.

monapay_test_zalo_groupGửi thử vào nhóm ZaloA

Gửi tin thử text thuần; nhóm phải có bot Gấu Mona vì Zalo không parse Markdown.

Inputs: id (required).

monapay_update_email_configSửa cấu hình thông báo emailB

Cập nhật tên, người nhận, sự kiện, VA hoặc trạng thái bật/tắt của cấu hình email. Người nhận mới phải xác minh trước khi cấu hình hoạt động. / Update an email config; new recipients must be verified before activation.

Inputs: config_id (required), name, events, is_active, +2 more.

monapay_update_webhookSửa cấu hình webhookC

Cập nhật webhook (URL, secret, bật/tắt). / Update a webhook config.

Inputs: config_id (required), name, auth_type, is_active, +5 more.

monapay_update_zalo_groupSửa nhóm ZaloC

Sửa cấu hình nhóm có bot Gấu Mona; group_id lấy từ MONA Account/PMS và template dùng text thuần vì Zalo không parse Markdown.

Inputs: id (required), events, group_id, is_active, +3 more.

monapay_verify_emailXác minh địa chỉ nhận emailA

Xác minh một người nhận bằng đúng mã 6 số người dùng đọc từ hộp thư; phải hỏi người dùng và không tự đoán mã. / Verify a recipient with the exact 6-digit code supplied by the user; never guess it.

Inputs: code (required), email (required), config_id (required).

monapay_verify_signatureKiểm chữ ký webhook (offline)A

Tính và so chữ ký HMAC-SHA256 của một webhook MONA Pay từ raw body + timestamp + secret, không gọi mạng. / Verify a webhook signature locally.

Inputs: secret (required), raw_body (required), signature (required), timestamp (required), +2 more.

monapay_webhook_logsLịch sử gửi webhookB

Lịch sử từng lần gửi (HTTP code, thời gian phản hồi, nhãn lỗi). / Webhook delivery logs.

Inputs: page, limit, status, to_date, +1 more.

monapay_webhook_statsThống kê webhookB

Tỷ lệ thành công, P95, phân loại lỗi. / Webhook delivery stats.

Inputs: no named parameters.

monapay_whoamiKiểm tra kết nối MONA PayA

Xác nhận client credentials đang hoạt động, trả tên tài khoản và gói hiện tại. / Verify connection and return account name and plan.

Inputs: no named parameters.

monapay_zalo_group_logsLịch sử gửi nhóm ZaloC

Tra lịch sử gửi vào nhóm Zalo, lọc trạng thái thành công hoặc thất bại.

Inputs: limit, status.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 50 tools

    Disambiguation4/5

    Most tools target a clearly distinct resource+action (checkouts, QR, webhooks, email, Zalo, keys, transactions), and the OTP/verification tools are well differentiated. The main overlap is monapay_me vs monapay_whoami, which both return account/connection profile info and could be confused, plus three separate 'verify_*' tools that need careful reading.

    Naming Consistency4/5

    Nearly everything follows a consistent monapay_verb_noun snake_case pattern (get_checkout, create_webhook, delete_zalo_group), which is very predictable. A few noun-only outliers (monapay_me, monapay_whoami, monapay_quickstart) break the verb pattern slightly.

    Tool Count2/5

    50 tools is heavy; while the domain genuinely spans multiple subsystems (bank linking, checkouts, QR, webhooks, email, Zalo, API keys), the surface is large enough to strain selection and could be consolidated (e.g. unified notification-channel CRUD). It sits at the extreme end of the recommended range.

    Completeness5/5

    Coverage is thorough: full CRUD plus test/logs/stats for webhooks, email and Zalo; a complete 4-step bank-linking OTP flow; checkout lifecycle (create/get/list/cancel); transactions, summaries, key management, signature verification and sandboxing. No obvious dead ends for the stated payment-receiving domain.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      Enables AI coding agents to integrate MONA Pay payments directly from the IDE, including creating VietQR codes, checking transactions, configuring and testing webhooks, verifying HMAC signatures, and generating webhook sample code.
      17
      124 npm
      MIT
    • A
      license
      C
      quality
      B
      maintenance
      A unified MCP server that lets AI agents (Claude Code, Codex, Cursor) deploy web apps and VPS instances, provision Supabase-compatible Postgres/Auth/Storage databases, register DNS domains, and send transactional email using a shared MONA Pass identity and VND wallet. It also embeds MONA Pay tooling for VietQR top-ups, checkout, webhooks and reconciliation, so agents can handle payment requests, budget approvals and resource lifecycles end to end.
      186
      144 npm
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents to integrate stablecoin crypto checkout into applications by registering workspaces, configuring settlement wallets and webhooks, creating payment links and invoices, and verifying payment status and webhook signatures. It exposes these payment operations as tools over stdio so agents can complete end-to-end payment setup without manual dashboard work.
      -