AgentPay VN 是为 AI 智能体设计的 VietQR 支付通道，提供 Python SDK 与 MCP 服务器，目标是在任何对话中完成收款。
用途 AgentPay VN 让 AI 智能体（Claude、GPT、自定义机器人）能够生成支付二维码、将其发送给用户，并在资金到达后自动确认——全程不持有或触碰资金。资金直接从付款人的银行账户流入商户账户；AgentPay 仅读取银行交易流水以确认结算。
主要能力
- 创建：智能体调用 POST /v1/payment-requests，获取 VietQR 图片 URL 和结账页面。
- 发送：智能体在聊天中嵌入二维码图片或发送结账链接。
- 等待：智能体调用 await_settlement()（或 MCP 工具）轮询，直到状态变为 settled。
- 交付：仅在确认结算后，智能体才释放商品或服务。 AgentPay 从不持有资金。二维码直接指向商户的银行账号，平台仅监控银行交易流水以检测匹配的转账。
使用方式
- 安装：参见仓库中的安装说明与示例（如 examples/quickstart.py）。
- 设置 API 密钥：从自托管的管理仪表盘获取密钥，或联系平台运营方。
- 收款（3 行代码）：完整可运行版本见 examples/quickstart.py。
- MCP 服务器设置：AgentPay 附带 MCP 服务器，任何兼容 MCP 的 AI 智能体均可将其作为工具调用，无需额外代码。
- Claude Desktop / Claude Code：添加到 claude_desktop_config.json（或使用 examples/claude_desktop_config.json），或使用已安装的控制台脚本。
- 可用的 MCP 工具。
- Webhook 验证：注册 Webhook 端点。
- OpenAPI 规范：agentpay-openapi.yaml
- 基础 URL：https://agentpay.servicesai.vn/v1
- 认证：Authorization: Bearer ap_live_xxx（沙箱使用 ap_test_xxx）
部署环境 AgentPay 作为 Sổ Nợ AI FastAPI 后端的一部分运行，包括：Docker Swarm 集群（与 Sono 相同）、MongoDB（与 Sono 共享）、SePay 银行流水账户（用于实时支付）、带 agentpay.servicesai.vn 虚拟主机的 Nginx。环境变量需自行配置。
创建 API 密钥（管理员） 响应包含完整密钥，需立即保存；密钥仅显示一次。
设计原则
- 不持有资金：二维码直接指向商户银行账户，AgentPay 仅读取交易流水，从不触碰资金。
- 幂等性：在 POST /payment-requests 上传递 Idempotency-Key 标头，可安全重试而不产生重复（24 小时去重窗口）。
- HMAC Webhook 验证：每个出站 Webhook 均使用 HMAC-SHA256(whsec_..., raw_body) 签名，置于 AgentPay-Signature 标头中。处理前务必验证。
- 沙箱：使用 ap_test_* 密钥和 POST /v1/sandbox/simulate-settlement，无需真实交易即可开发测试。
- 最小信任面：MCP 服务器是轻量 REST 客户端，除 API 密钥外无本地机密。智能体密钥泄露仅暴露单个租户的支付请求创建能力。
许可 MIT © 2026 ServicesAI — 详见 LICENSE。
