密钥介绍与配置
密钥类型
| 密钥 | 使用方 | 用途 |
|---|---|---|
| API Key | 商户调用接口服务 | 识别商户、凭据和产品权限；调用来源由平台运营侧安全组控制。 |
| API Secret | 仅商户后端使用 | 计算 HMAC-SHA256 请求签名，绝不随请求发送给接口服务。 |
| Webhook Secret | 商户 Webhook 接收端 | 校验平台投递给商户的 Webhook 通知，由 Webhook-Secret-Id 精确选择。 |
API Key 不是登录态 token，而是绑定商户编号和权限范围的凭据标识。API Secret 是用于证明调用方 持有该凭据的共享密钥。
关系模型
每个商户在每个环境最多有一把主 API Key 和一把替换 API Key。替换槽位用于在主 Key 仍提供服务时 部署并验证新 Key，切换完成后再吊销旧 Key，从而实现无停机轮换。每把 Key 只有一个当前 API Secret。
API 凭据与 Webhook Endpoint 是相互独立的资源。创建 Webhook 不要求先创建 API Key，API Key 的 启用、停用或吊销也不会改变 Webhook 投递。商户可创建多个 Endpoint；每个 Endpoint 包含一个 HTTPS URL、一个当前 Webhook Secret 和一个或多个事件订阅。同一事件类型可以同时投递到多个 Endpoint。
创建 Endpoint 或轮换 Secret 后，Portal 会将当前 Webhook Secret 和 Webhook Secret ID 明文显示 60 秒。接收端必须保存映射关系，例如：
Webhook-Secret-Id=whsecid_endpoint_a -> whsec_endpoint_a
Webhook-Secret-Id=whsecid_endpoint_b -> whsec_endpoint_b接收端必须按 Webhook-Secret-Id 选择 Secret，并在处理事件前校验 Signature。只要自动投递仍 可能使用旧 Endpoint 当时保存的 Secret，接收端就应保留对应的历史 Secret ID 映射。
创建凭据
商户在 Merchant Portal 的国际支付 API 接入入口创建凭据。API Secret 创建成功后只在当前页面会话中 展示一次，确认妥善保存前可在该页面继续复制；刷新或关闭浏览器后无法再次查看或找回。必须立即保存到 服务端密钥管理系统，例如 Vault、KMS 或受控环境变量管理系统。
Webhook Endpoint 在 Webhooks 模块独立创建，并为每个 Endpoint 选择事件。新 Endpoint 默认停用； 创建 Endpoint 不会改变 API Key 的鉴权状态。
不要把 API Secret 或 Webhook Secret 放到前端代码、移动端、仓库、日志、监控截图或工单中。
启用前检查
live 模式 API Key 在以下 API 检查通过前应保持停用：
- 商户准入和产品授权已完成；
- 国家、币种、产品、费率和结算账户已开通；
- 固定出口 IP 已由平台运营在安全组、WAF 或 API Gateway 批准；API 凭据不保存 IP 字段；
- 生产签名代码已通过请求签名测试向量。
Webhook 的启用是独立决策。只有事件订阅正确，且接收端能可靠接收签名事件时，才启用对应 Endpoint。 接收端正常场景返回 HTTP 200 OK，平台会将任意 2xx 响应视为接收成功。
轮换
API Key 或 API Secret 常规轮换时，先创建替代 API Key，让新旧 Key 短期并行。通过最近使用时间 确认切换完成后，先停用旧 Key 观察，确认无流量后永久吊销旧 Key。除非用于不同后端系统或权限 范围隔离，不建议长期保留替换 Key 活跃。
如果操作人暂时无法取得当前 API Secret，平台也不会再次展示或找回该 Secret；应创建替换 Key， 完成切换后吊销旧 Key。如果怀疑 Secret 已泄露，也应创建替换 Key 并吊销旧 Key。
Webhook 地址轮换时，创建独立的替换 Endpoint，选择相同事件，部署并启用新接收端后再停用旧 Endpoint。重叠启用期间，同一事件会同时投递到两个 Endpoint。直接修改 URL 会停用 Endpoint，并将待投递 记录标记为跳过，审核新接收端后再重新启用。
Webhook Secret 轮换前先停用该 Endpoint。Portal 生成新的 Webhook Secret ID 和版本，并将当前 Secret 明文显示 60 秒。轮换前已创建的初次投递和自动重试继续使用当时保存的 URL 与 Secret 版本； 人工补发使用 Endpoint 当前 URL 与当前 Secret。接收端在自动重试窗口内保留旧 Secret ID 映射， 窗口结束后再从商户密钥管理系统删除。