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 支付。
# ① 创建支付会话(任务预算 ¥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": "..." } } }
from payhub import PayHubClient client = PayHubClient("ph_live_...") # ① 创建支付会话(任务预算 ¥50) session = client.create_session( task_id="task-88", budget_limit={"amount": "50.00", "currency": "CNY"}, allowed_categories=["data"], # 可选:服务类别白名单 ) # ② 遇到 402 挑战,一行解决(自动支付 + 自动重试) result = client.resolve_and_retry(session.id, challenge) print(result.status) # paid print(result.data) # 200 OK 的业务数据
import { PayHub } from "@payhub/sdk"; const payhub = new PayHub(process.env.PAYHUB_TOKEN!); // ① 创建支付会话(任务预算 ¥50) const session = await payhub.sessions.create({ taskId: "task-88", budgetLimit: { amount: "50.00", currency: "CNY" }, }); // ② 遇到 402 挑战,一行解决(自动支付 + 自动重试) const result = await payhub.resolveAndRetry(session.id, challenge); console.log(result.status); // paid console.log(result.data); // 200 OK 的业务数据
402 Format
统一 402 响应格式
服务方只需产出这一种格式,微信 X402 / 支付宝 A2M 的方言由 PayHub 适配层转换。
{
"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-Key24 小时幂等窗口,重复请求不重复扣费。
API Reference
API 总览
四层接口:Agent 网关 · 服务方接入 · 授权预算 · 结算对账。
| 接口 | 方法 | 路径 | 用途 |
|---|---|---|---|
| 创建支付会话 | POST | /v1/agent/session | Agent 创建带预算的支付会话 |
| 解析 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 回放,本地即可完成全链路联调。