agentpay-vn
AgentPay VN's MCP server lets an agent create VietQR payment requests, monitor their status, wait for settlement, and reconcile recent payments.
create_payment_request: create a VND payment request with description, optional TTL, and internal metadata; returns an id, pay code, QR image URL, and checkout URL.check_payment: check a payment request's current status (pending,settled,underpaid,expired,cancelled) and amount received.await_settlement: poll every 5 seconds until a payment is settled/non-pending or the timeout is reached (10–600 seconds, default 180).list_recent_payments: list recently settled transactions for quick reconciliation (1–50 results, default 10).
AgentPay VN
VietQR payment infrastructure for AI agents — collect money inside any conversation.
AgentPay VN lets AI agents (Claude, GPT, custom bots) generate payment QR codes, send them to users, and automatically confirm when the money arrives — all without ever holding or touching funds. Money flows directly from the payer's bank account into the merchant's account; AgentPay only reads the bank transaction feed to confirm settlement.
Status: Early access / self-hosted — running on the same swarm as Sổ Nợ AI.
How it works
AI Agent AgentPay API Bank feed (SePay)
| | |
|-- create_payment_request ->| |
|<- { qr_image_url, id } ----| |
| | |
|-- send QR to user -------->| |
| | user scans & pays |
| |<-- webhook (bank txn) ----|
| |-- match AP* pay_code |
| |-- status → settled |
|<-- await_settlement done --| |
| | |
|-- deliver order / unlock ->| |Create — agent calls
POST /v1/payment-requests→ gets a VietQR image URL and a checkout page.Send — agent embeds the QR image or sends the checkout link to the user in chat.
Await — agent calls
await_settlement()(or the MCP tool) to poll untilstatus = settled.Deliver — only after confirmed settlement does the agent release the goods/service.
AgentPay never holds money. The QR points directly at the merchant's bank account number. The platform only monitors the bank transaction feed to detect matching transfers.
Related MCP server: Lightning Enable MCP
Quick start
1. Install
pip install agentpay-vn2. Get an API key — no account needed
A sandbox key is self-serve and instant:
curl -X POST https://agentpay.servicesai.vn/v1/sandbox/register \
-H "Content-Type: application/json" -d '{"shop_name": "My Bot"}'
# -> { "api_key": "ap_test_...", "expires_at": "..." }
export AGENTPAY_API_KEY=ap_test_xxxFrom Python: register_sandbox(). From an agent: just call the register_sandbox
MCP tool — it issues the key and applies it to the session.
Sandbox keys last 7 days, move no real money, and renew by calling the same endpoint
with the same email. For real payments you need an ap_live_* key, which requires a
registered merchant with a Vietnamese bank account — sign up at
agentpay.servicesai.vn.
3. Collect a payment (3 lines)
from agentpay.client import AsyncAgentPayClient, await_settlement
import asyncio
async def main():
async with AsyncAgentPayClient("ap_test_xxx") as client:
pr = await client.create_payment_request(amount=50_000, description="Order #1")
print(pr["checkout_url"]) # send this link to your user
result = await await_settlement(client, pr["id"], timeout=120)
assert result["status"] == "settled"
asyncio.run(main())See examples/quickstart.py for the full runnable version.
MCP server setup
AgentPay ships an MCP server so any MCP-compatible AI agent can call it as a tool — no extra code needed.
Claude Desktop / Claude Code
Add to claude_desktop_config.json (or use examples/claude_desktop_config.json):
{
"mcpServers": {
"agentpay": {
"command": "python",
"args": ["-m", "agentpay.mcp_server"],
"env": {
"AGENTPAY_API_KEY": "ap_test_xxx",
"AGENTPAY_BASE_URL": "https://agentpay.servicesai.vn/v1"
}
}
}
}Or use the installed console script:
{
"mcpServers": {
"agentpay": {
"command": "agentpay-mcp",
"env": { "AGENTPAY_API_KEY": "ap_live_xxx" }
}
}
}Available MCP tools
Tool | Description |
| Self-issue a free |
| Generate a VietQR code for a given amount |
| Get current status of a payment request |
| Poll until payment arrives or timeout (max 600 s) |
| List last N settled transactions |
Agent skill (Claude Code, Cursor, and other agents)
The MCP server gives an agent the tools. The bundled skill gives it the judgement:
when to charge, how to format a VND amount, and the rule that nothing ships before
status = settled. See skills/agentpay-vn/SKILL.md.
This repository is also a Claude Code plugin marketplace, so the skill and the MCP server install together in one step:
claude plugin marketplace add phuocdu/agentpay-vn
claude plugin install agentpay-vn@agentpay-vnClaude Code prompts for your API key (stored in the OS credential store, not in
settings.json). Leave it blank to start in sandbox — the agent will call
register_sandbox on its first charge.
For other agents, copy skills/agentpay-vn/ into wherever that agent reads skills from,
and add the MCP server as shown above.
Python SDK
Synchronous
from agentpay.client import AgentPayClient
with AgentPayClient("ap_live_xxx") as client:
# Create
pr = client.create_payment_request(
amount=150_000,
description="Consulting session 30 min",
ttl_minutes=30,
idempotency_key="session-abc-123",
)
# Poll manually
import time
for _ in range(60):
pr = client.get_payment_request(pr["id"])
if pr["status"] != "pending":
break
time.sleep(5)
# Reconcile
txns = client.list_transactions(limit=10)Asynchronous
from agentpay.client import AsyncAgentPayClient, await_settlement
async with AsyncAgentPayClient("ap_live_xxx") as client:
pr = await client.create_payment_request(amount=75_000, description="eBook download")
result = await await_settlement(client, pr["id"], timeout=300)
if result["status"] == "settled":
send_download_link(result["metadata"].get("email"))Webhook verification
import hashlib, hmac
def verify_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature_header)Register a webhook endpoint:
ep = client.register_webhook(
url="https://your-server.com/webhooks/agentpay",
events=["payment.settled", "payment.expired"],
)
print(ep["secret"]) # store this — shown only onceAPI reference
OpenAPI spec:
agentpay-openapi.yamlBase URL:
https://agentpay.servicesai.vn/v1Authentication:
Authorization: Bearer ap_live_xxx(orap_test_xxxfor sandbox)
Key endpoints
Method | Path | Description |
|
| Create payment request |
|
| Get status |
|
| Cancel pending request |
|
| List settled transactions |
|
| Register webhook URL |
|
| Simulate payment (sandbox only) |
|
| Public checkout page (HTML, mobile-friendly) |
Self-hosting
AgentPay runs as part of the Sổ Nợ AI FastAPI backend.
Requirements
Docker Swarm cluster (same as Sono)
MongoDB (shared with Sono)
SePay bank feed account (for live payments)
Nginx with an
agentpay.servicesai.vnvhost
Environment variables
Variable | Default | Description |
|
| Public base URL for checkout links |
|
| Inherited from Sono |
| — | SePay webhook token (inherited) |
Create an API key (admin)
curl -X POST https://sono.servicesai.vn/api/admin/agentpay/keys \
-H "Authorization: Bearer <admin-jwt>" \
-H "Content-Type: application/json" \
-d '{"org_id": "<shop-user-id>", "name": "My bot", "livemode": true}'The response includes the full key — store it immediately; it is shown only once.
Rate limits
Tier | Settled payments/month | Requests/minute |
Free | 50 | 120 |
Design principles
No money held — QR codes point directly at the merchant's bank account. AgentPay only reads the transaction feed; it never touches the money.
Idempotency — pass an
Idempotency-Keyheader onPOST /payment-requeststo safely retry without creating duplicates (24-hour deduplication window).HMAC webhook verification — every outbound webhook is signed with
HMAC-SHA256(whsec_..., raw_body)in theAgentPay-Signatureheader. Always verify before processing.Sandbox — use
ap_test_*keys andPOST /v1/sandbox/simulate-settlementto develop and test without real transactions.Minimal trust surface — the MCP server is a thin REST client with no local secrets beyond the API key. Compromising an agent key only exposes one tenant's payment-request creation ability.
License
MIT © 2026 ServicesAI — see LICENSE.
Available Tools
4 toolsawait_settlementA
Wait for a payment request to be settled (polls on behalf of the agent).
Polls every 5 seconds until status != pending or the timeout is reached (maximum 600 s). Call this after sending the QR to the payer. If the timeout expires while still pending, ask the user whether to keep waiting or cancel.
Args:
payment_request_id: The id returned by create_payment_request.
timeout_seconds: How long to wait in seconds (10–600, default 180).
Inputs: payment_request_id (required), timeout_seconds. Returns: result
check_paymentA
Check the current status of a payment request.
Returns: One of: pending | settled | underpaid | expired | cancelled, along with the amount received so far. Only treat a payment as complete when status=settled.
Inputs: payment_request_id (required). Returns: result
create_payment_requestA
Create a VietQR payment request.
Args: amount: Amount in VND, minimum 1 000. description: Short description for the payer (e.g. "Order #123 — 2 kg coffee"). ttl_minutes: QR validity window in minutes (5–1 440, default 60). metadata_note: Internal note from the agent (order id, conversation id, etc.) — echoed back in webhook events.
Returns:
id, pay_code, QR image URL, and checkout page URL. Send qr_image_url
or checkout_url to the payer, then call await_settlement(id) to
wait for the money to arrive.
Inputs: amount (required), description (required), ttl_minutes, metadata_note. Returns: result
list_recent_paymentsB
List the most recently settled transactions (quick reconciliation).
Args: limit: Number of transactions to return (1–50, default 10).
Inputs: limit. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a distinct and clear purpose: creating a payment request, checking status, awaiting settlement, and listing recent payments. No two tools overlap in functionality, ensuring an agent can easily select the correct one.
All tool names follow a consistent verb_noun snake_case pattern (create_payment_request, check_payment, await_settlement, list_recent_payments). The naming is predictable and unambiguous.
Four tools is a reasonable number for a focused payment processing server. While it covers core operations, it is slightly lean; adding a cancel tool might improve completeness, but the count is appropriate.
The tool set covers the main lifecycle of a payment request: create, check, await, and list. Missing an explicit cancel/expire function, but the await tool handles timeouts gracefully. Minor gap, but overall sufficient for typical workflows.
Maintenance
Related MCP Connectors
Vietnam payments for AI agents — MoMo wallet QR, ATM, cards. Zero-setup sandbox. Never holds funds.
MCP marketplace: AI agents buy services from other agents per call in USDC, plus a bank cash-out
Agent Commerce Protocol MCP — bridges Stripe ACP + Google AP2 + Coinbase x402 for agent payments
HiveCapital MCP Server — autonomous investment layer for AI agents
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP server for AgentPay — the payment gateway for autonomous AI agents. Fund a wallet once, give your agent the key, and it discovers, provisions, and pays for tool APIs on its own. One key, every tool.112 npm1MIT
- AlicenseAqualityBmaintenanceMCP server that enables AI agents to make autonomous Bitcoin Lightning Network payments using the L402 protocol. Agents can pay for API access, purchase resources, and complete transactions without human intervention — invoice comes in, sats go out, done.179MIT
- AlicenseAqualityBmaintenanceCredit and payments for AI agent developers — over MCP. No crypto required6514 npm4MIT
- AlicenseNot gradedqualityBmaintenanceA remote MCP server that lets any AI agent accept PromptPay QR, credit/debit cards, TrueMoney wallet, internet banking payments in Thailand, and check payment status.MIT