AgentPay VN

AgentPay VN

面向 AI Agent 的 VietQR 支付基础设施 — 在任何对话中收款。

AgentPay VN 可让 AI Agent（Claude、GPT、自定义机器人）生成支付二维码并发送给用户，在款项到账后自动确认 — 全程无需持有或经手资金。款项直接从付款人的银行账户转入商户账户；AgentPay 只读取银行交易记录以确认结算。

状态： 早期访问／可自托管 — 运行在与 Sổ Nợ AI 相同的集群上。

---

工作原理

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

1. 创建 — Agent 调用 POST /v1/payment-requests → 获取 VietQR 图片 URL 和结账页面。
2. 发送 — Agent 在聊天中嵌入二维码图片，或将结账链接发送给用户。
3. 等待 — Agent 调用 await_settlement()（或 MCP 工具），轮询直到 status = settled。
4. 交付 — 只有在确认结算后，Agent 才会交付商品／服务。

AgentPay 绝不持有资金。 二维码直接指向商户的银行账户号码。平台只监控银行交易记录，以检测匹配的转账。

---

快速开始

1. 安装

pip install agentpay-vn

2. 获取 API 密钥 — 无需账户

沙盒密钥可自行申请，即时获取：

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

在 Python 中：register_sandbox()。通过 Agent：只需调用 register_sandbox MCP 工具 — 它会签发密钥并将其应用到会话中。

沙盒密钥有效期为 7 天，不涉及真实资金；使用相同的 email 再次调用同一端点即可续期。若要进行真实支付，则需要 ap_live_* 密钥，这要求先注册商户并绑定越南银行账户 — 请前往 agentpay.servicesai.vn 注册。

3. 收款（3 行代码）

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())

完整的可运行版本请参见 examples/quickstart.py。

---

MCP 服务设置

AgentPay 提供了一个 MCP 服务，任何兼容 MCP 的 AI Agent 都可以将其作为工具调用 — 无需额外编写代码。

Claude Desktop / Claude Code

添加到 claude_desktop_config.json（或使用 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"
      }
    }
  }
}

或者使用已安装的控制台脚本：

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "env": { "AGENTPAY_API_KEY": "ap_live_xxx" }
    }
  }
}

可用的 MCP 工具

工具	描述
register_sandbox	自行签发免费的 ap_test_* 密钥 — 尚未设置密钥时请先调用此工具
create_payment_request	为指定金额生成 VietQR 二维码
check_payment	获取支付请求的当前状态
await_settlement	轮询直至收到款项或超时（最长 600 s）
list_recent_payments	列出最近 N 笔已结算交易

---

Agent 技能（Claude Code、Cursor 和其他 Agent）

MCP 服务提供 Agent 所需的工具。捆绑的技能则提供判断力： 何时收费、如何格式化 VND 金额，以及在 status = settled 之前不得发货的规则。请参见 skills/agentpay-vn/SKILL.md。

此仓库也是 Claude Code 插件市场，因此技能和 MCP 服务可以一步安装：

claude plugin marketplace add phuocdu/agentpay-vn
claude plugin install agentpay-vn@agentpay-vn

Claude Code 会提示输入 API 密钥（存储在操作系统凭据库中，而非 settings.json）。留空即可从沙盒开始 — Agent 会在首次收费时调用 register_sandbox。

对于其他 Agent，请将 skills/agentpay-vn/ 复制到该 Agent 读取技能的目录， 并按上文所示添加 MCP 服务。

---

Python SDK

同步

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)

异步

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 验证

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 端点：

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 参考

• OpenAPI 规范： 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 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 令牌（从 Sono 继承）

创建 API 密钥（管理员）

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 都会在 AgentPay-Signature 标头中使用 HMAC-SHA256(whsec_..., raw_body) 签名。处理前务必验证。

4. 沙盒 — 使用 ap_test_* 密钥和 POST /v1/sandbox/simulate-settlement，无需真实交易即可开发和测试。

5. 最小信任面 — MCP 服务是轻量级 REST 客户端，除 API 密钥外没有本地机密信息。若 Agent 密钥遭到泄露，攻击者只能获得创建单个租户付款请求的能力。

---

许可证

MIT © 2026 ServicesAI — 详见 LICENSE。