三行代码,让 Agent 学会花钱

统一的支付会话与 402 挑战解析接口:创建会话、转发挑战、自动重试。 服务方注册资源一次,全部 Agent 平台的用户都能调用并完成支付。

Idempotency-Key 全链路幂等 RSA-SHA256 回调验签 沙箱环境免费
Onboarding

四步接入

① 注册资源

在 PayHub 登记资源与定价(按次 / 按 Token / 阶梯),声明收款账户。

POST /v1/merchant/resources

② 引入 SDK

Agent 侧安装 Python / TypeScript SDK,或直接用 curl 调用统一接口。

pip / npm

③ 创建支付会话

任务开始前创建会话,设定预算与允许的服务类别。

POST /v1/agent/session

④ 遇 402 自动支付

转发挑战 → 自动支付 → 携带凭据重试,Agent 任务无感继续。

POST /v1/agent/resolve-402
Quickstart

快速开始

创建支付会话 + 解析 402 挑战,跑通第一笔 Agent 支付。

quickstart.sh
# ① 创建支付会话(任务预算 ¥50)
curl -X POST https://api.payhub.cn/v1/agent/session \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -d '{ "task_id": "task-88",
       "budget_limit": { "amount": "50.00", "currency": "CNY" } }'
# → { "session_id": "ps_abc123", "status": "active" }

# ② 遇到 402,转发挑战给 PayHub
curl -X POST https://api.payhub.cn/v1/agent/resolve-402 \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Idempotency-Key: task-88-402-01" \
  -d '{ "session_id": "ps_abc123",
       "resource_url": "https://api.marketdata.cn/v1/premium",
       "payment_required": { "scheme": "exact", "amount": "0.50", "currency": "CNY" } }'
# → { "status": "paid", "retry_instructions": { "headers": { "PAYMENT-RESPONSE": "..." } } }
402 Format

统一 402 响应格式

服务方只需产出这一种格式,微信 X402 / 支付宝 A2M 的方言由 PayHub 适配层转换。

challenge.json
{
  "scheme":    "exact",        // exact | tiered
  "amount":    "0.50",        // CNY,tiered 时为数组
  "currency":  "CNY",
  "recipient": "merchant_id_123",
  "resource":  "marketdata/v1",
  "metering":  { "unit": "call" },
  "expires_at": 1759300800,       // 最长 15 分钟
  "accepts":   ["payhub", "x402"]
}
  • 双通道声明:响应头 PAYMENT-REQUIRED + 响应体标准块,兼容只读 body 的 Agent。
  • 两种触发模式:402 主动挑战与 200 内嵌支付提示块均支持。
  • 凭据回传:支付后经 PAYMENT-RESPONSE 头注入重试请求,响应体同格式附带。
  • 幂等保障:Idempotency-Key 24 小时幂等窗口,重复请求不重复扣费。
API Reference

API 总览

四层接口:Agent 网关 · 服务方接入 · 授权预算 · 结算对账。

接口方法路径用途
创建支付会话POST/v1/agent/sessionAgent 创建带预算的支付会话
解析 402 挑战POST/v1/agent/resolve-402处理付费资源返回的 402 并自动支付
查询支付状态GET/v1/agent/payment/{id}查询单笔支付状态
预下单POST/v1/merchant/preorder服务方登记支付条件(复用传统下单结果)
资源注册POST/v1/merchant/resources注册可被 Agent 调用的付费资源
收款账户绑定POST/v1/merchant/payout-account绑定持牌通道收款账户
创建授权策略POST/v1/auth/policies定义预算与分级授权规则
实时账单GET/v1/auth/billing按任务 / Agent 查询支付记录
调整预算PATCH/v1/auth/session/{id}实时调整会话预算或关闭会话
紧急停止POST/v1/auth/emergency-stop冻结指定 Agent 或全部支付能力
统一对账GET/v1/settlement/reconciliation跨通道、跨平台统一对账单
结算导出GET/v1/settlement/export按维度导出结算明细
Agent 注册(KYA)POST/v1/kya/agents注册 Agent 身份并获取签名密钥
可信等级查询GET/v1/kya/agents/{id}/trust-level查询 Agent 可信等级
Webhooks

Webhook 事件

RSA-SHA256 签名回调,与主流通道验签机制保持一致。

事件触发时机接收方
payment.succeeded支付成功服务方 + Agent 开发者
payment.failed支付失败服务方 + Agent 开发者
payment.expired支付凭据过期服务方
budget.warning预算使用达 80%用户 / 管理员
budget.exhausted预算耗尽用户 / 管理员 + Agent
session.closed支付会话关闭Agent 开发者
settlement.completed结算完成创作者 / 商户
SDK & Tools

SDK 与工具

即将发布

Python / TypeScript SDK

pip install payhub / npm i @payhub/sdk:会话管理、402 处理、自动重试、验签工具。

即将发布

MCP Server

把支付能力暴露为 MCP 工具,任意支持 MCP 的智能体即可调用支付会话与 402 解析。

即将发布

调试工具

402 挑战模拟器、签名校验器、Webhook 回放,本地即可完成全链路联调。

已上线

llms.txt

面向大模型的站点说明文件,Agent 读它即可理解 PayHub 的能力与接入方式。查看 →

领取沙箱密钥,现在开始

注册即获测试额度,30 分钟跑通第一笔 Agent 支付。