常见问题 FAQ

签名 / 认证

返回 401 或签名失败怎么办？

确认 Access Key 正确且凭证未停用
服务器时间与标准时间差是否在 ±5 分钟 内（建议开 NTP）
签名 PATH 是否为 /v1/...，且不含 query
GET 请求 body 哈希是否为空串的固定 SHA-256
POST 的 body 是否与发送字节完全一致（不要二次序列化）
私钥是否为 PKCS#8 格式（与 SDK 示例一致）

Nonce 相关错误？

每个请求使用新的 UUID；5 分钟内不可重复。

假密钥疯狂请求会怎样？

同一 IP 约 20 次/分钟后返回 429（请求过于频繁），请勿对生产做爆破测试。

权限 / 网络

403 开发者权限？

管理端为该商户开通 API 接入 后重试。

403 IP 不在白名单？

把调用服务器出口公网 IP 配进控制台白名单（注意 NAT / 代理真实出口）。

连接超时？

先用沙箱 Base URL：https://uat-openapi.cafinx.com/v1/ping；检查防火墙是否放行 HTTPS 出站。

业务

42201 余额不足？

USD 不足且自动兑币后仍不足。请先充值 USD 或数字货币后重试。

42202 BIN 不可用？

bin 必须来自 GET /card-products 当前可开列表。

是不是所有开卡都要做 KYC？

不是。 以 GET /card-products 返回的 requireThirdPartyKyc 为准：

目录字段	是否要 KYC	开卡怎么做
`requireThirdPartyKyc: true`	要	控制台一键认证，或请求带 `kycProvider` + `kycReferenceId`
`requireThirdPartyKyc: false`	不要	正常 `POST /cards`，不必传 KYC 字段

完整分支说明见 卡产品与身份认证。

开卡提示须完成身份认证？

仅当该 bin 在目录中为 requireThirdPartyKyc=true 时才会出现。两种方式：

控制台一键认证 通过后，平台自动附带凭证；或
开卡请求透传（对接方自有 KYC，不限 Didit）：

POST /cards
{
  "bin": "46651711",
  "creditLimit": "20",
  "kycProvider": "DIDIT",
  "kycReferenceId": "your-vendor-session-or-applicant-id"
}

kycProvider	说明
`DIDIT`	Didit（平台控制台默认）
`SUMSUB`	Sumsub
`MyInfo`	MyInfo
`Jumio`	Jumio
`Shufti`	Shufti

请求级凭证 优先于 控制台落库。只接 Didit 时固定 DIDIT 即可；其他服务商换枚举 + 其 Reference。

持卡人不能跨卡段复用？

是。holderId 须与当前 bin 的产品线匹配；不同产品线持卡人档案隔离。
建议：开卡前用与 bin 对应的持卡人列表（商户后台按卡段筛选），或省略 holderId 由平台按 holderName 自动建档。

40302 操作状态不允许？

例如对 CLOSED（已销卡）再充值、对 ACTIVE（正常）再解冻。按当前 status 选择合法操作。

写接口提示缺幂等键？

所有 POST 写接口必须带 X-Idempotency-Key（建议业务单号）。

同幂等键第二次结果不一样？

同键必须同 body；否则返回 40901（幂等冲突）。需要新业务请换新键。

钱包流水里出现 chargeback_fee / auth_fee？

type	含义
`chargeback_fee`	交易授权拒绝后的拒付费（平台配置的固定金额）
`auth_fee`	授权相关费用（按平台/商户费率从钱包扣除；可高于成本加价）

二者均为出账（amount 为负），余额不足时仍可能记负，不自动兑数字货币。
已开通开放 API 的商户：拒付费连续不足不会因此自动限制账户；未开通 API 的个人账户可能按平台规则被限制。详见变更日志 v1.8。

Webhook

收不到回调？

控制台是否启用 Webhook 且 URL 公网可达
是否被 SSRF 规则拒绝（内网地址不可用）
事件是否在订阅列表内
控制台投递记录是否 FAILED（可手动重发）

验签总是失败？

必须用原始 body 字节验签；Express 等框架勿先 JSON.parse 再 stringify。

文档与规范

如何拿到 OpenAPI？

文档站 API Reference（自动生成）
或请求：GET https://openapi.cafinx.com/v1/openapi.json?locale=zh-CN（沙箱将域名换成 uat-openapi）

SDK 怎么装？

参考仓库 docs/developer-sdk/ 下各语言源码，按文件头注释安装依赖（Java 无三方依赖；Python 需 cryptography 等）。当前为示例源码形态，非强制 npm/Maven 中央仓库版本。

技术支持？

请通过商户控制台工单 / 客户成功经理或平台约定邮箱联系；请附带 requestId、时间戳与脱敏请求路径。