持卡人要求
- 调用 List Products，并以目标产品的
required_fields为准。Enhanced KYC 产品要求提供identity、residential_address和kyc_verification；如果产品只要求 Simplified KYC 字段，现有的持卡人创建流程无需改动。 first_name与last_name的总长度不能超过 26 个字母。residential_address.postal_code长度必须为 4–10 位（含两端）。
概览
前置条件
调用 API 之前，先获取 Access Token：x-auth-token 请求头传入返回的 auth_token。
步骤1：检查产品要求
调用 List Products 查看目标产品要求哪些字段。required_fields 数组。Enhanced KYC 产品的必填字段会包含 identity、residential_address 和 kyc_verification。以下是一个 Enhanced 产品的示例（BIN 46651711）：
required_fields 告诉你具体需要哪些信息。只有标注 "required": true 的字段是必填的 —— 可选字段可以省略。步骤2：使用 Enhanced KYC 创建持卡人
调用 Create Cardholder，传入完整的必填字段以及kyc_verification。
共有两种验证方式，根据你的场景选择：
方式 A：SUMSUB_REDIRECT
如果你希望 UQPAY 通过 Sumsub 处理身份验证，使用此方式。你会收到一个 IDV URL 用于重定向持卡人。INCOMPLETE 状态，并附带一个 IDV 链接：
idv_verification_url 完成身份验证，然后等待 webhook 通知（见步骤3）。
方式 B：THIRD_PARTY
如果你已通过自有 KYC 服务商完成持卡人身份验证并有凭证引用，使用此方式。将
<reference_id> 替换为 KYC 服务商提供的全局唯一引用 ID。kyc_proof.reference_id 长度须为 10–64 个字符，包含两端。步骤3：等待 KYC 审核通过（仅 SUMSUB_REDIRECT）
如果你使用了SUMSUB_REDIRECT，订阅 cardholder.kyc.status_changed webhook，在 KYC 审核完成或需要补充资料时接收通知。根据 data.cardholder_status 处理结果：
SUCCESS：审核通过，可以继续发卡。FAILED：审核被拒绝，请勿发卡。INCOMPLETE：需要补充或更正资料。处理资料要求后，等待状态变为SUCCESS再发卡。
data.reason 在有可用拒绝或补充资料说明时包含该说明，无可用说明或审核通过时为空；请勿仅凭说明为空判断审核通过。
Webhook payload 示例（KYC 已通过）：
cardholder_status 变为 SUCCESS 时，持卡人即可签发卡片。
持卡人处于
PENDING 状态时无法签发卡片。请先等待 KYC 审核通过。步骤4：创建卡片
当cardholder_status 为 SUCCESS 后，调用 Create Card：
下方示例使用沙盒环境的
card_currency: "USD"。生产环境下请将 card_currency 设置为 XUSD。错误处理
建卡时 KYC 信息不足
如果持卡人尚未满足产品的 KYC 要求就尝试创建卡片，你会收到如下错误，其中missing_fields 指明仍需补齐的字段：
- 先通过 Update Cardholder 更新持卡人信息，然后重试建卡。
- 在 Create Card 请求中通过
cardholder_required_fields字段内联补充缺失的信息。
持卡人处于 PENDING 状态
持卡人cardholder_status 为 PENDING 时创建卡片会被拒绝。请等待 KYC 审核完成后再重试。