卡产品与身份认证

不强制所有卡都做 KYC。 是否需要，以 GET /card-products 里该产品的字段为准。
对接方应先拉目录、再按产品分支，不要写死「所有开卡都要认证」或「永远不要认证」。

1. 先读产品目录

GET /card-products

重点字段：

字段	类型	含义
`bin`	string	开卡时必须使用的卡头，来自本列表
`requireThirdPartyKyc`	boolean	`true`：本产品须提供身份认证 Reference；`false`：不要求
`needCardHolder`	boolean	是否须关联持卡人档案
`cardHolderModel`	string	业务模型码，如 `B2C` / `B2B`（展示/对接参考）
`productLabel`	string	产品线角标文案（可选）
`feeNotes`	string[]	费率补充说明（可选，多条）
`minTopup`	string	最低首充 USD
`cardOpenFeeFixed` / `cardOpenFeePercent`	string	开卡费拆分

示例分支

GET /card-products
        │
        ├─ requireThirdPartyKyc === true
        │         → 开卡前准备 KYC（见第 2 节）
        │         → POST /cards 时带 kyc 或依赖控制台已认证
        │
        └─ requireThirdPartyKyc === false（或未返回/视为 false）
                  → 直接 POST /cards（bin + creditLimit 等）
                  → 不要强行传 KYC 字段

2. 当 `requireThirdPartyKyc = true`

二选一（请求级优先）：

A. 开卡请求透传（对接方自有 KYC 流程）

商户用自己的 Didit / Sumsub / Jumio 等完成认证后：

POST /cards
{
  "bin": "46651711",
  "creditLimit": "20.00",
  "kycProvider": "DIDIT",
  "kycReferenceId": "第三方返回的 Reference / Session ID"
}

kycProvider	服务商
`DIDIT`	Didit
`SUMSUB`	Sumsub
`MyInfo`	MyInfo
`Jumio`	Jumio
`Shufti`	Shufti

只接 Didit 的对接方：固定 kycProvider=DIDIT 即可。
接其他家的：换对应枚举 + 其 Reference ID，不必走平台控制台 Didit。

B. 控制台一键认证

在商户控制台完成平台提供的一键身份认证并通过后，平台会保存凭证。
之后 POST /cards 可不传 kycProvider / kycReferenceId，平台自动附带。
若请求里也传了，以请求为准。

缺少凭证时

业务失败（友好提示须完成身份认证或传入 Reference）。
不会在 requireThirdPartyKyc=false 的产品上强制要求。

3. 当 `requireThirdPartyKyc = false`

正常 POST /cards：bin、creditLimit、可选 holderId / holderName / alias
不要依赖 KYC 字段；传了一般可忽略，但以产品规则为准
适合不需要终端用户身份档案的产品线

4. 持卡人与产品线

holderId 须与当前 bin 同一产品线（不同卡段的持卡人不可混用）
可用商户后台按卡段筛选的持卡人列表，或省略 holderId 由平台按姓名自动建档
与是否 KYC 独立：KYC 解决「认证凭证」；持卡人解决「卡上姓名档案」

5. 推荐对接伪代码

const products = await api.get('/card-products');
const product = products.find(p => p.bin === chosenBin);
if (!product) throw new Error('BIN not in catalog');

const body = {
  bin: product.bin,
  creditLimit: String(Math.max(Number(product.minTopup) || 5, amount)),
};

if (product.requireThirdPartyKyc === true) {
  // 自有 KYC：填入 reference；或已在控制台认证则可不填
  body.kycProvider = 'DIDIT'; // 或 SUMSUB / MyInfo / Jumio / Shufti
  body.kycReferenceId = await yourKycFlow.getReferenceId();
}

await api.post('/cards', body, { idempotencyKey: orderId });

6. 与资金、幂等

开卡扣费规则不变：USD 钱包 + 自动兑币；X-Idempotency-Key 必填
KYC 失败通常在扣款后回滚或业务拒绝（以响应 code/message 为准）；请按幂等键安全重试