phuocdu/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
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
2. Set your API key
Get a key from the admin dashboard (self-hosted) or contact the platform operator.
3. Collect a payment (3 lines)
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):
Or use the installed console script:
Available MCP tools
| Tool | Description |
|------|-------------|
| create_payment_request | Generate a VietQR code for a given amount |
| check_payment | Get current status of a payment request |
| await_settlement | Poll until payment arrives or timeout (max 600 s) |
| list_recent_payments | List last N settled transactions |
---
Python SDK
Synchronous
Asynchronous
Webhook verification
Register a webhook endpoint:
---
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
| Method | Path | Description |
|--------|------|-------------|
| POST | /v1/payment-requests | Create payment request |
| GET | /v1/payment-requests/{id} | Get status |
| POST | /v1/payment-requests/{id}/cancel | Cancel pending request |
| GET | /v1/transactions | List settled transactions |
| POST | /v1/webhook-endpoints | Register webhook URL |
| POST | /v1/sandbox/simulate-settlement | Simulate payment (sandbox only) |
| GET | /pay/{pay_code} | 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.vn vhost