Dành cho AI agent

claude mcp add monapay -e MONAPAY_CLIENT_ID=client_xxx -e MONAPAY_CLIENT_SECRET=xxx -- npx -y monapay-mcp

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

Tích hợp MONA Pay (API ngân hàng nội địa Việt Nam, nhận và xác nhận tiền chuyển khoản ngân hàng theo thời gian thực) vào dự án của tôi.

Tài liệu: https://monapay.vn/llms-full.txt (toàn văn), https://monapay.vn/openapi.json
Base URL API: https://api.monapay.vn (alias cũ: https://ipn.mona.host)
Xác thực (dành cho agent, KHÔNG dùng username/mật khẩu của tôi): POST /api/v1/oauth/token với grant_type=client_credentials, client_id, client_secret (tôi lấy ở my.monapay.vn → API Keys) → data.access_token (Bearer, hạn 3600 giây, hết hạn thì gọi lại).
POST/PUT/DELETE gửi thêm header X-Client-Secret = client_secret.
Mọi response: {"success": bool, "message": str, "data": any}.

Việc cần làm:
1. Tạo endpoint HTTPS POST /webhook/monapay trong dự án để nhận thông báo tiền vào. MONA Pay POST JSON:
   {"amount":2500000,"description":"noi dung ck","transfer_date":"10:30:00 28/08/2026","transaction_code":"FT26240001234","account_number":"MONA0000010234","bank_name":"ACB","type":"income"}
2. Verify chữ ký: header X-Mona-Signature = "sha256=" + hex(HMAC-SHA256(secret, X-Mona-Timestamp + "." + raw_body)).
   Từ chối nếu |now - X-Mona-Timestamp| > 300 giây. So sánh chữ ký bằng hàm timing-safe. Đọc raw body, không parse trước khi ký.
3. Chống trùng bằng transaction_code (UNIQUE). Bỏ qua transaction_code = "DUMMY123" (payload gửi thử).
4. Trả HTTP 200 ngay trong 10 giây, xử lý đơn hàng bất đồng bộ. Khớp đơn theo account_number (số VA) hoặc mã đơn trong description, và so amount với số tiền đơn.
5. Đăng ký URL webhook: POST /api/v1/client-webhooks {name, webhook_url, auth_type:"HMAC_SHA256", secret_key} (Bearer + X-Client-Secret), rồi gửi thử POST /api/v1/client-webhooks/test {webhook_url, auth_type, secret_key, is_dummy:true}.
6. Nối ngân hàng ngay trong cuộc trò chuyện này, không bắt tôi mở dashboard: hỏi tôi số tài khoản ACB, số điện thoại đã đăng ký với ngân hàng, loại khách hàng (cá nhân/doanh nghiệp), đầu số VA và nội dung định danh; gọi POST /api/v1/acb/virtual-account/registration; báo tôi rằng ACB đã gửi OTP về điện thoại và HỎI tôi mã OTP; gọi POST /api/v1/acb/{acb_request_id}/virtual-account/verification {code}; rồi gọi POST /api/v1/acb/{virtual_account_id}/notification/registration, hỏi tôi OTP lần 2, gọi POST /api/v1/acb/{acb_request_id}/notification/verification {code}. Không bao giờ tự đoán OTP. Chi tiết body ở https://monapay.vn/docs/api/tai-khoan-ao-va.md
7. Cấu hình email: gọi monapay_create_email_config; hỏi tôi mã 6 số trong hộp thư; chỉ sau khi tôi trả lời mới gọi monapay_verify_email; rồi gọi monapay_test_email và monapay_email_logs, xác nhận status sent. Không tự đoán mã.
8. Nếu tôi cần báo vào nhóm Zalo: hỏi group_id do MONA Account cung cấp; gọi monapay_create_zalo_group, lấy id, gọi monapay_test_zalo_group rồi monapay_zalo_group_logs; chỉ xác nhận xong khi status ok. Nhóm phải có bot Gấu Mona. Zalo không parse Markdown.
client_id, client_secret và secret HMAC đọc từ biến môi trường MONAPAY_CLIENT_ID, MONAPAY_CLIENT_SECRET, MONA_WEBHOOK_SECRET; không ghi cứng.

BASE=https://api.monapay.vn

# 1. Đổi client_id + client_secret (dashboard → API Keys) ra Bearer token, hạn 3600 giây
CLIENT_ID=client_xxx
SECRET=xxx
TOKEN=$(curl -s -X POST $BASE/api/v1/oauth/token \
  -d "grant_type=client_credentials&client_id=$CLIENT_ID&client_secret=$SECRET" | jq -r .data.access_token)

# 2. (Chỉ khi là người đăng nhập tay) POST /api/v1/client/login {username,password} cũng trả Bearer; agent không dùng cách này

# 3. Secret HMAC do bạn tự sinh, dùng chung giữa MONA Pay (ký) và server bạn (verify)
WEBHOOK_SECRET=$(openssl rand -hex 32)

# 4. Đăng ký URL webhook với HMAC-SHA256
curl -s -X POST $BASE/api/v1/client-webhooks \
  -H "Authorization: Bearer $TOKEN" -H "X-Client-Secret: $SECRET" -H 'Content-Type: application/json' \
  -d "{\"name\":\"Web ban hang\",\"webhook_url\":\"https://shop.vn/webhook/monapay\",\"auth_type\":\"HMAC_SHA256\",\"secret_key\":\"$WEBHOOK_SECRET\",\"payload_format\":\"application/json\"}"

# 5. Gửi thử payload giả lập (transaction_code = DUMMY123)
curl -s -X POST $BASE/api/v1/client-webhooks/test \
  -H "Authorization: Bearer $TOKEN" -H "X-Client-Secret: $SECRET" -H 'Content-Type: application/json' \
  -d "{\"webhook_url\":\"https://shop.vn/webhook/monapay\",\"auth_type\":\"HMAC_SHA256\",\"secret_key\":\"$WEBHOOK_SECRET\",\"is_dummy\":true}"

# 6. Đọc log lần gửi thử: status_code, duration_ms, error_label
curl -s "$BASE/api/v1/webhook-logs?limit=5" -H "Authorization: Bearer $TOKEN" | jq '.data.items[0]'

SECRET='secret_hmac_test'
URL='http://localhost:3000/webhook/monapay'
TS=$(date +%s)
BODY='{"amount":2500000,"description":"noi dung ck","transfer_date":"10:30:00 28/08/2026","transaction_code":"FT26240001234","account_number":"MONA0000010234","bank_name":"ACB","type":"income"}'
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
curl -X POST "$URL" -H 'Content-Type: application/json' \
  -H "X-Mona-Timestamp: $TS" -H "X-Mona-Signature: sha256=$SIG" --data "$BODY"

curl -X POST $BASE/api/v1/sandbox/transactions \
  -H "Authorization: Bearer $TOKEN" -H "X-Client-Secret: $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"amount":10000,"description":"DH10234 test sandbox"}'

<?php
$secret = getenv('MONA_WEBHOOK_SECRET');
$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_MONA_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_MONA_SIGNATURE'] ?? '';
if (abs(time() - (int) $ts) > 300) { http_response_code(400); exit; }
if (!hash_equals('sha256=' . hash_hmac('sha256', "$ts.$raw", $secret), $sig)) { http_response_code(401); exit; }
http_response_code(200); echo 'OK';
if (function_exists('fastcgi_finish_request')) fastcgi_finish_request();
$d = json_decode($raw, true);
if ($d['transaction_code'] === 'DUMMY123') exit;
// INSERT IGNORE theo UNIQUE(transaction_code), rồi khớp đơn theo account_number / description, so amount

app.post('/webhook/monapay', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.header('X-Mona-Timestamp') || '', sig = req.header('X-Mona-Signature') || '';
  const raw = req.body.toString('utf8');
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);
  const exp = 'sha256=' + crypto.createHmac('sha256', process.env.MONA_WEBHOOK_SECRET).update(`${ts}.${raw}`).digest('hex');
  if (sig.length !== exp.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(exp))) return res.sendStatus(401);
  res.sendStatus(200);
  const d = JSON.parse(raw);
  if (d.transaction_code === 'DUMMY123') return;
  queue.add('monapay', d); // upsert theo transaction_code, khớp đơn, so amount
});