AgentPay VN

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)

1. Create — agent calls POST /v1/payment-requests → gets a VietQR image URL and a checkout page.
2. Send — agent embeds the QR image or sends the checkout link to the user in chat.
3. Await — agent calls await_settlement() (or the MCP tool) to poll until status = settled.
4. 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.

---

Quick start

1. Install

pip install agentpay-vn

2. 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_xxx

From 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

---

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-vn

Claude 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 once

---

API reference

• OpenAPI spec: agentpay-openapi.yaml
• Base URL: https://agentpay.servicesai.vn/v1
• Authentication: Authorization: Bearer ap_live_xxx (or ap_test_xxx for sandbox)

Key endpoints

---

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.vn vhost

Environment variables

Create an API key (admin)

curl -X POST https://sono.servicesai.vn/api/admin/agentpay/keys \

-H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"org_id": " ", "name": "My bot", "livemode": true}'

The response includes the full key — store it immediately; it is shown only once.

---

Rate limits

---

Design principles

1. No money held — QR codes point directly at the merchant's bank account. AgentPay only reads the transaction feed; it never touches the money.

1. Idempotency — pass an Idempotency-Key header on POST /payment-requests to safely retry without creating duplicates (24-hour deduplication window).

1. HMAC webhook verification — every outbound webhook is signed with HMAC-SHA256(whsec_..., raw_body) in the AgentPay-Signature header. Always verify before processing.

1. Sandbox — use ap_test_* keys and POST /v1/sandbox/simulate-settlement to develop and test without real transactions.

1. 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.