内容
# AgentPay 越南
<!-- mcp-name: io.github.phuocdu/agentpay-vn -->
[](https://pypi.org/project/agentpay-vn/)
[](LICENSE)
[](https://registry.modelcontextprotocol.io/v0/servers?search=agentpay-vn)
[](https://glama.ai/mcp/servers/phuocdu/agentpay-vn)
**用于 AI 代理的 VietQR 支付基础设施 — 在任何对话中收款。**
AgentPay 越南允许 AI 代理（Claude、GPT、自定义机器人）生成支付二维码，将其发送给用户，并在资金到账时自动确认 — 整个过程无需持有或接触资金。资金直接从付款人的银行账户流入商户的账户；AgentPay 仅读取银行交易信息流以确认结算。
> **状态：** 早期访问 / 自托管 — 在与 [Sổ Nợ AI](https://sono.servicesai.vn) 相同的 swarm 上运行。
---
## 工作原理
```
AI 代理 AgentPay API 银行信息流（SePay）
| | |
|-- create_payment_request ->| |
|<- { qr_image_url, id } ----| |
| | |
|-- send QR to user -------->| |
| | 用户扫描并支付 |
| |<-- webhook（银行交易）----|
| |-- 匹配 AP* pay_code |
| |-- 状态 → 已结算 |
|<-- await_settlement 完成 --| |
| | |
|-- 交付订单 / 解锁 ->| |
```
1. **创建** — 代理调用 `POST /v1/payment-requests` → 获取 VietQR 图片网址和结算页面。
2. **发送** — 代理在聊天中将二维码图片或结算链接嵌入或发送给用户。
3. **等待** — 代理调用 `await_settlement()`（或 MCP 工具）以轮询直到 `status = settled`。
4. **交付** — 仅在确认结算后，代理才释放商品/服务。
**AgentPay 永远不会持有资金。** 二维码直接指向商户的银行账户号码。平台仅监视银行交易信息流以检测匹配的转账。
---
## 快速开始
### 1. 安装
```bash
pip install agentpay-vn
```
### 2. 设置 API 密钥
```bash
export AGENTPAY_API_KEY=ap_test_xxx # 用于测试的沙盒密钥
```
从管理仪表板（自托管）或联系平台运营商获取密钥。
### 3. 收集付款（3 行代码）
```python
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="订单 #1")
print(pr["checkout_url"]) # 将此链接发送给用户
result = await await_settlement(client, pr["id"], timeout=120)
assert result["status"] == "settled"
asyncio.run(main())
```
参见 [`examples/quickstart.py`](examples/quickstart.py) 获取完整的可运行版本。
---
## MCP 服务器设置
AgentPay 配备了一个 [MCP](https://modelcontextprotocol.io) 服务器，因此任何与 MCP 兼容的 AI 代理都可以调用它作为工具 — 无需额外代码。
### Claude Desktop / Claude 代码
添加到 `claude_desktop_config.json`（或使用 [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json)）：
```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"
}
}
}
}
```
或使用已安装的控制台脚本：
```json
{
"mcpServers": {
"agentpay": {
"command": "agentpay-mcp",
"env": { "AGENTPAY_API_KEY": "ap_live_xxx" }
}
}
}
```
### 可用的 MCP 工具
| 工具 | 描述 |
|------|-------------|
| `create_payment_request` | 为给定金额生成 VietQR 代码 |
| `check_payment` | 获取支付请求的当前状态 |
| `await_settlement` | 轮询直到支付到账或超时（最大 600 秒） |
| `list_recent_payments` | 列出最近的 N 笔已结算交易 |
---
## Python SDK
### 同步
```python
from agentpay.client import AgentPayClient
with AgentPayClient("ap_live_xxx") as client:
# 创建
pr = client.create_payment_request(
amount=150_000,
description="咨询会话 30 分钟",
ttl_minutes=30,
idempotency_key="session-abc-123",
)
# 手动轮询
import time
for _ in range(60):
pr = client.get_payment_request(pr["id"])
if pr["status"] != "pending":
break
time.sleep(5)
# 对账
txns = client.list_transactions(limit=10)
```
### 异步
```python
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="电子书下载")
result = await await_settlement(client, pr["id"], timeout=300)
if result["status"] == "settled":
send_download_link(result["metadata"].get("email"))
```
### Webhook 验证
```python
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)
```
注册 webhook 端点：
```python
ep = client.register_webhook(
url="https://your-server.com/webhooks/agentpay",
events=["payment.settled", "payment.expired"],
)
print(ep["secret"]) # 存储此密钥 — 仅显示一次
```
---
## API 参考
- **OpenAPI 规范：** [`agentpay-openapi.yaml`](agentpay-openapi.yaml)
- **基准 URL：** `https://agentpay.servicesai.vn/v1`
- **身份验证：** `Authorization: Bearer ap_live_xxx`（或 `ap_test_xxx` 用于沙盒）
### 关键端点
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `POST` | `/v1/payment-requests` | 创建支付请求 |
| `GET` | `/v1/payment-requests/{id}` | 获取状态 |
| `POST` | `/v1/payment-requests/{id}/cancel` | 取消待处理请求 |
| `GET` | `/v1/transactions` | 列出已结算交易 |
| `POST` | `/v1/webhook-endpoints` | 注册 webhook URL |
| `POST` | `/v1/sandbox/simulate-settlement` | 模拟支付（仅限沙盒） |
| `GET` | `/pay/{pay_code}` | 公共结算页面（HTML，移动友好） |
---
## 自托管
AgentPay 作为 [Sổ Nợ AI](https://sono.servicesai.vn) FastAPI 后端的组成部分运行。
### 要求
- Docker Swarm 集群（与 Sono 相同）
- MongoDB（与 Sono 共享）
- SePay 银行信息流账户（用于实时支付）
- 具有 `agentpay.servicesai.vn` 虚拟主机的 Nginx
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `AGENTPAY_BASE_URL` | `https://agentpay.servicesai.vn` | 结算链接的公共基准 URL |
| `MONGO_URI` | `mongodb://localhost:27017` | 从 Sono 继承 |
| `BILLING_WEBHOOK_TOKEN` | — | SePay webhook 令牌（继承） |
### 创建 API 密钥（管理员）
```bash
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}'
```
响应包含完整的密钥 — 立即存储；它只显示一次。
---
## 速率限制
| 层级 | 每月结算支付 | 每分钟请求 |
|------|----------------------|-----------------|
| 免费 | 50 | 120 |
---
## 设计原则
1. **不持有资金** — 二维码直接指向商户的银行账户号码。AgentPay 仅读取交易信息流；它从不接触资金。
2. **幂等性** — 在 `POST /payment-requests` 上传递 `Idempotency-Key` 头部，以安全地重试而不会创建重复项（24 小时去重窗口）。
3. **HMAC webhook 验证** — 每个出站 webhook 都使用 `HMAC-SHA256(whsec_..., raw_body)` 在 `AgentPay-Signature` 头部中签名。始终验证后再处理。
4. **沙盒** — 使用 `ap_test_*` 密钥和 `POST /v1/sandbox/simulate-settlement` 来开发和测试而无需真实交易。
5. **最小信任表面** — MCP 服务器是一个薄的 REST 客户端，除了 API 密钥外，没有本地秘密。破坏代理密钥只会暴露一个租户的支付请求创建能力。
---
## 许可证
MIT © 2026 ServicesAI — 参见 [LICENSE](LICENSE)。
