● 对接说明

对接说明

以 SDK 方式为例走一遍。HPP 把第 2 步换成重定向,H2H 把第 2 步换成你自己收卡号并做字段加密,其余一致。

1. 端到端四步

1
建客户端会话绑定金额、订单号、客户,换一个 24 小时过期的 client token
2
渲染收银台前端用 publishable key + client token 挂载 SDK,拿到 payment_method token
3
建支付服务端带幂等键和签名创建,路由引擎选通道,软拒自动级联
4
收回调验签 → 去重 → 定序 → 5 秒内返 2xx
# 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 管不到的那几件事:

威胁TLSbody 签名
公网链路被窃听或篡改✅✅(冗余一层)
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

请求头

AuthorizationBearer sk_live_xxx
X-Signature-Versionv1,为将来换算法留的位
X-TimestampUnix 秒。与服务端偏差超过 ±300 秒直接拒
X-Nonce随机串,10 分钟内不可重复,用于防重放
X-Signaturehex(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_failedcapture / 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 找我们,或先看错误码自查——九成问题在那张表里。 →