最佳实践

1. 环境与密钥

• 联调只用沙箱 Base URL；生产密钥与沙箱密钥分开
• 私钥仅存服务端密钥管理系统；禁止进前端与仓库
• 生产强制 IP 白名单 + HTTPS

2. 写接口与幂等

• 所有 POST 写接口带稳定业务单号作 X-Idempotency-Key
• 网络超时重试时复用同一幂等键，避免重复扣款
• 换业务内容必须换新键（否则可能 40901）

3. 错误重试

4. Webhook

• 先落库/入队再返回 2xx
• 以 eventId 幂等去重
• 对原始 body 验签；未知 eventType 也返回 2xx
• 生产回调仅 HTTPS；勿用内网地址

5. 对账

• 钱包：GET /wallet/flows（关注 type=swap 自动兑换）
• 卡交易：GET /transactions 按时间与 cardId 拉取
• 以平台流水为准做差异排查

6. 敏感信息

• 列表/详情默认只有 cardNoLast4
• 完整卡号仅 GET /cards/{id}/secure，限流更严；用完即弃，勿写日志

7. 并发

• 同一卡的充值/转出避免无序并发；必要时串行或依赖幂等键
• 共享池附属卡批量开卡注意开卡费合计与钱包余额

8. 卡产品与 KYC（按产品分支，勿全局强制）

• 先目录后开卡：GET /card-products → 读 requireThirdPartyKyc / minTopup / feeNotes
• requireThirdPartyKyc === true：控制台一键认证 或 POST /cards 传 kycProvider + kycReferenceId（DIDIT / SUMSUB / MyInfo / Jumio / Shufti）
• requireThirdPartyKyc === false：不要当成必须 KYC；正常传 bin + 金额即可
• 只接 Didit 的对接方：固定 kycProvider=DIDIT 即可；其他服务商用对应枚举 + 其 Reference ID
• 持卡人 holderId 与当前 bin 同产品线，不可混用
• 完整说明：卡产品与身份认证