集成检查清单

按顺序勾选。完成后你应能在沙箱稳定调用写接口并正确接收 Webhook。

A. 开通与凭证

• 商户控制台已开通 API / 开发者 权限（未开通 → 网关 403）
• 已生成 RSA 密钥对；私钥仅存服务端
• 公钥已上传；已拿到 ak_ Access Key
• 沙箱与生产使用不同密钥与白名单（如已分环境）

B. 网络与环境

• 调用机出口 IP 已加入白名单（含 NAT 真实出口）
• 使用正确 Base URL
  • 沙箱：https://uat-openapi.cafinx.com/v1
  • 生产：https://openapi.cafinx.com/v1
• 服务器时间 NTP 同步（签名时间窗 ±5 分钟）
• 出站 HTTPS 可达上述域名

C. 第一个成功调用

• GET /ping 返回信封 code=200
• 签名 PATH 为 /v1/...，不含 query、不含域名
• GET 的 body 哈希使用空串固定 SHA-256
• 每个请求新 X-Nonce；时钟漂移在允许范围内

D. 写接口与资金

• 所有 POST 写接口携带稳定 X-Idempotency-Key
• 超时重试复用同一幂等键
• 已理解：消费只扣 USD，不足自动兑币；42201 = 仍不足
• bin 仅来自 GET /card-products 当前列表
• 已解析目录字段：requireThirdPartyKyc / minTopup / cardOpenFeeFixed / feeNotes / productLabel
• 代码按 requireThirdPartyKyc 分支（true 才走 KYC，false 不强制）
• true 产品：控制台已认证，或 POST /cards 带 kycProvider + kycReferenceId
• false 产品：开卡路径不依赖 KYC 字段
• holderId 与当前 bin 同产品线（不可混用）；或 holderName / 省略由平台建档
• 完整卡号仅通过 GET /cards/{id}/secure 临时获取，不落日志
• 已阅读 卡产品与身份认证

E. Webhook

• 控制台配置了可公网访问的 HTTPS 回调 URL（商户域名）
• 对原始 body 验签；先落库/入队再返回 2xx
• 以 eventId 幂等去重
• 未知 eventType 仍返回 2xx，避免无意义重试风暴

F. 规范与工具下载（商户控制台内一键下载）

登录商户后台 → 开发者 → 工具与状态（或 API 文档页顶部快捷按钮）：

G. 上线生产前

• 沙箱完成：开卡 → 充值/转出 → 查询交易 → Webhook 联调
• 生产密钥、白名单、Webhook URL 已切换且已回归签名
• 已阅读 安全声明（或控制台安全声明页）与 最佳实践
• 告警：签名失败率、429、Webhook 连续失败、余额不足

H. 服务水平（摘要 · 非合同）

完整条款见 服务水平（SLA）（与主协议冲突时以合同为准）。摘要：

完成后

优先阅读：快速开始 · 认证与签名 · 错误码 · Webhook · SLA · 服务状态