● 开放 API · /v1 · 50 个接口

对接方式

先选一条路,再看「对接说明」。三条路共用同一套 /v1 接口和同一套回调,差别只在卡数据经不经过你的服务器——这一条决定了你的 PCI 范围和接入工期。

选哪一条

托管收银台(HPP)

SAQ-A

自己没有前端团队、想最快上线、不介意跳转到我们托管的页面

建支付时拿 client token,把买家重定向到我们托管的收银页。支付方式、3DS、本地化全由我们渲染,你只收回调。

工期
1–2 天
链路
建客户端会话 → 重定向买家 → 收回调 → 查单核对

Web / App SDK

SAQ-A

要把收银台嵌在自己页面里、保留品牌和结账流程

卡号字段跑在我们域名下的 iframe 里,你的页面拿不到卡数据,PCI 范围仍是 SAQ-A。样式可配置。

工期
3–5 天
链路
建客户端会话 → SDK 挂载 → 拿 payment_method token → 服务端建支付 → 收回调

服务端直连(H2H)

SAQ-D

已有 PCI DSS 认证、要完全自建收银界面

卡数据经你的服务器传给我们,你必须自己承担 PCI DSS Level 1 合规成本。没有现成认证不要选这条。

工期
2–4 周 + PCI 审计
链路
自建收银界面 → 卡字段数字信封加密 → 服务端建支付(L2 签名)→ 处理 3DS 跳转 → 收回调

没有 PCI DSS 认证就不要选 H2H。卡号一旦进入你的服务器,你的整套基础设施都进入审计范围,年度成本以十万计。前两条路卡号只在我们域名下的 iframe / 托管页里,你的范围是 SAQ-A。

环境与域名

密钥前缀即环境,前缀和域名必须一致。用 sk_test_ 打 live 域名会直接 401,不会误扣真钱。

环境域名密钥前缀
live https://api.baton.example sk_live_ / pk_live_
test https://api.sandbox.baton.example sk_test_ / pk_test_

secret key 只在服务端用。一旦请求里出现浏览器的 Origin / Referer 头,我们直接拒绝并告警——这是最高频的泄漏事故。

开放能力

14 组、50 个接口。文档由 OpenAPI 契约生成,契约即事实源。 OpenAPI 契约

3

客户端会话

把一笔待支付的上下文换成短时效 client token,交给前端 SDK 或托管收银台渲染,卡号不经过你的服务器。

7

支付

一个接口覆盖全部渠道。创建后由路由引擎决定走哪条通道,软拒自动级联到备用渠道。

4

支付尝试

一笔支付由 N 次尝试组成,每次尝试对应一个渠道。尝试被显式建模,级联过程可查可干预。

5

支付方式与金库

卡数据只存在于金库,你的系统里只有 token。支持复用、设为默认、删除。

3

客户

把商户侧用户映射成 Baton 客户,用于绑卡复用、风控画像与争议举证。

4

出款

向收款人付钱。签名要求比收款高一级(L2 非对称签名),收款账号字段必须加密传输。

2

争议

拉取拒付与争议,上传举证材料。举证窗口由卡组织规定,过期不可补。

1

汇率

查询用于多币种定价的参考汇率。结算汇率以渠道实际回执为准。

3

退款

退款是独立资源,有自己的单号和状态。渠道可能几天后才拒退,退款的失败必须能单独查到。

2

文件

上传争议举证材料。文件只用于指定用途,不做通用网盘。

5

余额与对账

余额、结算批次、明细导出。给你的 ERP 和财务系统自动拉数用,不用人去后台点。

6

回调管理

注册端点、轮换密钥、查投递记录、手动重发。你的系统挂过一段时间之后,靠这组接口自助补齐。

3

路由编排

路由规则走配置即代码:从代码仓库发布、带版本号、可先模拟再发布。不把编排锁在控制台里。

2

渠道透传

把你的原始请求转发给指定渠道,金库里的卡数据在转发时替换进去。用于 Baton 尚未抽象的渠道私有能力。