凭据与密钥

对接前需要备齐 4 个凭据。本页说明每个凭据是什么、去哪里获取、商户密钥对如何生成，以及 IP 白名单机制。

对接所需的 4 个凭据

对接需要 4 个值（向平台获取 / 在商户后台查看，请妥善保管，切勿外泄）：

名称	说明	用途
`APP-ID`	商户号	请求头标识
`TOKEN`（或获取 token 的 secret）	接口令牌	鉴权
`服务端公钥 public_t`	平台公钥，`base64(PEM)`	加密上行请求 / 验证下行签名
`商户私钥 private_u`	你的私钥，`base64(PEM)`	签名上行请求 / 解密下行数据

密钥格式 = base64(PEM)

即对标准 PEM 文本（-----BEGIN ... KEY----- 整段）再做一次 Base64。各语言 SDK 会先 Base64 解码还原 PEM，再加载。私钥为 PKCS#8（BEGIN PRIVATE KEY），公钥为 SPKI（BEGIN PUBLIC KEY）。密钥为 RSA-2048。

其中 TOKEN 不是静态凭据：用 APP-ID + secret 调用 getToken 换取，有效期内复用即可。真正需要长期保管的是 secret、public_t 和 private_u。

在商户后台获取

凭据	获取方式
`APP-ID`	即商户 id，在商户后台的商户列表 / 商户详情中可见
`secret`	商户后台「API 对接凭据」页查看
`服务端公钥 public_t`	商户后台「API 对接凭据」页查看
`商户私钥 private_u`	商户自行生成（见下节），平台不提供、不保存

后台展示的是 PEM 明文，SDK 需要的是 base64(PEM)

「API 对接凭据」页展示的公钥是 PEM 明文（-----BEGIN PUBLIC KEY----- 整段），而 SDK 构造函数需要的是对整段 PEM 再做一次 Base64 的结果。后台提供两种复制按钮（复制 PEM 明文 / 复制 base64(PEM)），对接 SDK 时请使用 base64(PEM) 那个，不要直接粘 PEM 明文。

生成密钥对后，把公钥通过商户后台的「上传商户公钥」提交给平台（提交时需要 Google 2FA 验证）。私钥留在你自己的服务器上。

未上传公钥前业务接口不可用

平台侧未配置你的公钥时，业务接口会返回 publicKeyNotExist（PUBLIC U 未配置）。请先完成公钥上传，再开始联调。

生成商户密钥对（openssl）

bash

# 1. 生成 RSA-2048 私钥（PKCS#8 格式，BEGIN PRIVATE KEY）
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private_u.pem

# 2. 从私钥导出公钥（SPKI 格式，BEGIN PUBLIC KEY）
openssl pkey -in private_u.pem -pubout -out public_u.pem

# 3. 转成 SDK 需要的 base64(PEM)（-w0 表示不换行）
base64 -w0 private_u.pem > private_u.b64
base64 -w0 public_u.pem  > public_u.b64

public_u.pem 的内容通过后台「上传商户公钥」提交给平台。
private_u.b64 的内容作为 SDK 构造函数的商户私钥参数。
private_u.pem / private_u.b64 权限收紧（如 chmod 600），只存在你的服务端。

IP 白名单

平台对每个商户号维护来源 IP 白名单，业务请求的来源 IP 不在白名单内时，返回纯文本 Oops（不是 JSON，也没有错误码）。

收到 Oops 时先确认你服务器的实际出口 IP，再联系平台核对白名单。
多出口 / NAT / 负载均衡 / 云函数等场景下，出口 IP 可能不止一个，必须把所有可能的出口 IP 全部加白，否则会出现「偶发 Oops」的诡异现象。

实现细节：白名单校验在最前面

服务端中间件的校验顺序为：请求体大小 → 商户存在 → IP 白名单 → token → 公钥 → 签名/解密。也就是说，白名单不通过时根本走不到 token 和签名校验——如果你确定凭据和 SDK 都没问题却拿到 Oops，问题一定在来源 IP 上。

更多错误现象排查见错误码与排障指南。

安全须知

私钥只属于你，平台永不持有

private_u 由你自行生成，平台不提供、不保存、也永远不会向你索要。任何以「官方」「客服」「技术支持」名义索要商户私钥（或私钥文件、base64 串）的，一律是诈骗。私钥仅存于你的服务端，切勿写入前端、日志或第三方。

换钥即时生效，请在低峰操作

通过「上传商户公钥」提交新公钥后，平台立即以新公钥验签，旧私钥随即失效——用旧私钥签名/解密的请求会全部失败。请：

选择业务低峰时段操作；
提前在服务端备好新私钥，上传新公钥后立即切换；
切换后立刻调用 selfcheck 跑通上下行链路，确认无误再恢复业务流量。

下一步

理解加密、签名与防重放的完整规范：协议规范
用 secret 换取 token：getToken
各语言 SDK 如何加载这两个 base64(PEM) 密钥：SDK 使用

凭据与密钥 ​

对接所需的 4 个凭据 ​

在商户后台获取 ​

生成商户密钥对（openssl） ​

IP 白名单 ​

安全须知 ​