对接说明
以 SDK 方式为例走一遍。HPP 把第 2 步换成重定向,H2H 把第 2 步换成你自己收卡号并做字段加密,其余一致。
1. 端到端四步
# 1) 服务端建客户端会话,拿 client token
curl -X POST https://api.baton.example/v1/checkout/sessions \
-H "Authorization: Bearer sk_live_xxx" \
-H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
-H "Content-Type: application/json" \
-d '{"reference_id":"OR20261116000104","amount":8900,"currency":"USD"}'
# 2) 前端用 client_token 渲染收银台,拿到 payment_method token
# 卡号在我们域名的 iframe 里,不进你的页面、不进你的服务器
# 3) 服务端建支付
curl -X POST https://api.baton.example/v1/payments \
-H "Authorization: Bearer sk_live_xxx" \
-H "Idempotency-Key: 01J8ZQ4T7M2K9F3C" \
-H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a9c2e" -H "X-Signature: v1=..." \
-H "Content-Type: application/json" \
-d '{"reference_id":"OR20261116000104","amount":8900,"currency":"USD",
"payment_method":{"token":"pm_7c2a91f4"}}'
# 4) 收回调。最终结果以回调为准,不以第 3 步的同步响应为准 client token 不要落库、不要复用。它绑定一笔待支付的上下文,泄漏等于把这笔支付的发起权交出去。
2. 鉴权与签名
读接口只要 Bearer;所有写接口必须额外签名。出款与卡数据直传再上一级,用 Ed25519 非对称签名加字段级数字信封。
| 级别 | 适用接口 | 方案 |
|---|---|---|
L0 | 查询、创建客户端会话 | TLS + Bearer sk_live_... |
L1 | 全部写操作 | Bearer + HMAC-SHA256 签名 |
L2 | 出款、卡号直传 | Ed25519 签名 + 字段加密 |
签名到底防什么(不是「有了 HTTPS 就不用签」)
TLS 保的是公网链路。签名保的是端到端——它防的是 TLS 管不到的那几件事:
| 威胁 | TLS | body 签名 |
|---|---|---|
| 公网链路被窃听或篡改 | ✅ | ✅(冗余一层) |
| TLS 终止之后被改:CDN / WAF / 网关到后端那段是明文,企业出口的 TLS 拦截代理也能改 | ❌ | ✅ |
| 重放:把你发过的一笔退款原样再发一次 | ❌ | ✅ 靠 timestamp + nonce |
换接口重放:拿 /refund 的签名去打 /capture | ❌ | ✅ 靠签名串里的 METHOD 与 path |
| 不可抵赖:事后争议「这笔不是我发的」 | ❌ | ✅ 日志里存签名即证据 |
少签 METHOD 或 path 是真实事故来源。只签 body 的话,同一个 {"amount":2000} 的签名能同时用在退款和扣款上。这也是签名串有六段、不是只签 body 的原因。
为什么出款要换成非对称签名
HMAC 是双方共享同一把密钥:我们的库被脱,就能伪造你的请求。Ed25519 的私钥只在你手里,我们只存公钥——验得了、签不了。出款是资损敞口最大的接口,值这个复杂度。
待签名串
六段用换行连接,顺序固定。第六段是请求体原始字节的 SHA-256 十六进制值,不要反序列化后重新序列化再算——各语言的 JSON 键序、空格、转义不一致,重排必然对不上。
v1 POST /v1/payments 1763280000 7f3a9c2e e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
请求头
Authorization | Bearer sk_live_xxx |
X-Signature-Version | v1,为将来换算法留的位 |
X-Timestamp | Unix 秒。与服务端偏差超过 ±300 秒直接拒 |
X-Nonce | 随机串,10 分钟内不可重复,用于防重放 |
X-Signature | hex(hmac_sha256(secret, 待签名串))。服务端用常量时间比较 |
我们不做整包加密:网关无法路由、日志无法排障、你的接入成本翻倍,收益低于 TLS 已提供的保障。只有卡号、CVV、收款账号这类字段走信封加密。
3. 幂等与重试
所有 POST 必带 Idempotency-Key,建议直接用业务单号派生。24 小时内重放同一 key 返回首次结果;同 key 配不同请求体返回 409,不会悄悄产生第二笔。
| 情况 | 该怎么做 |
|---|---|
| 网络超时、没拿到响应 | 用同一个 key 重试,或调 GET /v1/payments/{uid} 查实际结果 |
返回 5xx / 503 | 同 key 指数退避重试 |
返回 4xx | 请求本身有问题,改了再发,换新 key |
返回 429 | 立刻停,按 Retry-After 等。继续打会被临时封禁 |
重试时 X-Nonce 和 X-Timestamp 必须换新的,Idempotency-Key 必须保持不变。两者作用相反,别搞混。
4. 三条不会变的状态约定
failed和cancelled是终态。迟到的成功回调不会把它们翻回成功——真要翻,走人工补偿,不走自动流程。timeout不是失败。它是「结果未知」。不要当失败重试,否则可能重复扣款;调查询接口收敛,或等对账补偿。- 硬拒不重试。
decline_type=hard(挂失、止付、风控拒)重试只会加剧风控,我们直接终止级联。
判断能做什么操作,看响应里的 available_actions 和 is_terminal,不要自己用 status 枚举推——这两个值是后端算好的,枚举会加。
5. 回调
同步响应是「此刻的状态」,最终结果以回调为准。回调方向用 HMAC(你验签成本最低):
X-Signature: t=1763280000,v1=5d41402a...,v1=7d793037...
签名串是 {timestamp}.{请求体原文}。v1 出现两次是轮换期新旧密钥各签一次,任意一个验过即可,你不用停机换密钥。
接收端四条硬要求
- 先验签再解析。验签失败返回 401 并丢弃,不要落库。
- 按事件
id去重。同一事件会重投;重复处理一次退款就是真金白银。 - 按
updated定序。投递不保证顺序,用时间戳丢弃旧状态,别用到达顺序。 - 5 秒内返回 2xx。慢了算失败,按 1 / 2 / 3 / 4 分钟退避重投,连续失败则停投并在控制台告警。
事件列表
| 事件 | 说明 | payload |
|---|---|---|
payment.status_changed | 支付状态变更(含授权成功、扣款成功、失败、取消) | Payment |
refund.status_changed | 退款状态变更。**渠道可能在发起几天后才拒退,这个事件是唯一能知道的途径** | Refund |
payment.operation_failed | capture / void / refund 等操作在渠道侧失败 | Payment |
payment_attempt.requires_action | 某次尝试需要外部动作(3DS 跳转、二维码、重定向) | Attempt |
payout.status_changed | 出款状态变更 | Payout |
dispute.opened | 新争议产生,注意举证截止时间 | Dispute |
dispute.status_changed | 争议状态变更(举证已受理、胜诉、败诉) | Dispute |
routing.evaluation_failed | 路由规则求值失败(规则引用了已下线的渠道、条件字段拼错)。此时走默认路由,但你必须知道 | SimulateResult |
settlement.ready | 一个结算批次已入账并完成对账,可以拉明细了 | Settlement |
6. 上线前自查
- 幂等键由业务单号派生,不是随机生成后丢掉——否则重试时你拿不回同一个 key。
- 回调接口做了去重和定序,并且先验签再解析。
- 金额全程用整数最小币种单位,展示时才按
currency_exponent换算。不在浏览器里算钱。 - 密钥不在代码仓库、不在前端包、不在日志里;日志有正则兜底脱敏。
- test 环境跑过一遍失败路径:硬拒、超时、重复回调、超额退款。只测成功路径等于没测。
对不上时:拿响应里的 request_id 找我们,或先看错误码自查——九成问题在那张表里。 →