Enhanced KYC 发卡流程

仅 Personal Visa Personal Visa 卡产品要求持卡人先完成 Enhanced KYC，才能签发卡片。本指南涵盖从检查产品要求、完成持卡人身份验证到成功签发卡片的完整流程。

只有当 cardholder_status 为 SUCCESS 时才能发卡。 持卡人处于 INCOMPLETE、PENDING 或 FAILED 状态时，请勿调用 Create Card；必须先完成或处理 KYC。

Personal Visa 开卡受持卡人地区限制。 持卡人的 residential_address.country 和 nationality 决定其是否具备开卡资格。若居住国家/地区不受支持或国籍受限制，Create Card 请求将被拒绝。建议在创建持卡人并发起 KYC 前，先查看完整的持卡人地区限制，避免完成 KYC 后仍无法开卡。

持卡人要求

调用 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：

curl -X POST "https://api-sandbox.uqpaytech.com/api/v1/connect/token" \
  -H "Content-Type: application/json" \
  -H "x-api-key: {your_api_key}" \
  -H "x-client-id: {your_client_id}"

{
  "auth_token": "eyJhbGciOiJIUzI1NiIs...",
  "expired_at": 1775210493
}

后续所有请求都通过 x-auth-token 请求头传入返回的 auth_token。

步骤1：检查产品要求

调用 List Products 查看目标产品要求哪些字段。

curl -X GET "https://api-sandbox.uqpaytech.com/api/v1/issuing/products?page_size=10&page_number=1" \
  -H "Content-Type: application/json" \
  -H "x-auth-token: {your_auth_token}"

查看响应中的 required_fields 数组。Enhanced KYC 产品的必填字段会包含 identity、residential_address 和 kyc_verification。以下是一个 Enhanced 产品的示例（BIN 46651711）：

{
  "product_id": "0d8f10de-c888-4107-ab65-1cc9deb31b3b",
  "card_bin": "46651711",
  "card_scheme": "VISA",
  "card_form": ["VIR"],
  "card_currency": ["USD", "SGD", "HKD"],
  "mode_type": "SHARE",
  "kyc_level": "ENHANCED",
  "max_card_quota": 3001,
  "product_status": "ENABLED",
  "required_fields": [
    { "name": "first_name", "type": "string", "required": true },
    { "name": "last_name", "type": "string", "required": true },
    { "name": "email", "type": "string", "required": true },
    { "name": "country_code", "type": "string", "required": true },
    { "name": "date_of_birth", "type": "string", "required": true },
    { "name": "phone_number", "type": "string", "required": true },
    { "name": "nationality", "type": "string", "required": true },
    {
      "name": "identity",
      "type": "object",
      "required": true,
      "fields": [
        { "name": "type", "type": "string", "required": true },
        { "name": "number", "type": "string", "required": true },
        { "name": "front_file", "type": "string", "required": true },
        { "name": "back_file", "type": "string", "required": false },
        { "name": "hand_file", "type": "string", "required": false }
      ]
    },
    {
      "name": "residential_address",
      "type": "object",
      "required": true,
      "fields": [
        { "name": "country", "type": "string", "required": true },
        { "name": "state", "type": "string", "required": true },
        { "name": "city", "type": "string", "required": true },
        { "name": "district", "type": "string", "required": false },
        { "name": "line1", "type": "string", "required": true },
        { "name": "line2", "type": "string", "required": false },
        { "name": "line_en", "type": "string", "required": true },
        { "name": "postal_code", "type": "string", "required": true }
      ]
    },
    {
      "name": "kyc_verification",
      "type": "object",
      "required": true,
      "fields": [
        { "name": "method", "type": "string", "required": true },
        {
          "name": "kyc_proof",
          "type": "object",
          "required": false,
          "fields": [
            { "name": "provider", "type": "string", "required": false },
            { "name": "reference_id", "type": "string", "required": false }
          ]
        }
      ]
    }
  ]
}

required_fields 告诉你具体需要哪些信息。只有标注 "required": true 的字段是必填的 —— 可选字段可以省略。

步骤2：使用 Enhanced KYC 创建持卡人

调用 Create Cardholder，传入完整的必填字段以及 kyc_verification。共有两种验证方式，根据你的场景选择：

方式	适用场景	结果
`SUMSUB_REDIRECT`	希望由 UQPAY 通过 Sumsub 处理 IDV	返回 IDV URL，供持卡人完成验证
`THIRD_PARTY`	你已通过自有 KYC 服务商完成持卡人验证	持卡人立即完成验证

方式 A：SUMSUB_REDIRECT

如果你希望 UQPAY 通过 Sumsub 处理身份验证，使用此方式。你会收到一个 IDV URL 用于重定向持卡人。

curl -X POST "https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders" \
  -H "Content-Type: application/json" \
  -H "x-auth-token: {your_auth_token}" \
  -H "x-idempotency-key: cc58fa96-7a49-4be1-a70b-85075c1b4957" \
  -d '{
    "first_name": "Sarah",
    "last_name": "Chen",
    "email": "sarah.chen@example.com",
    "country_code": "SG",
    "phone_number": "90755646",
    "date_of_birth": "1992-06-15",
    "nationality": "SG",
    "identity": {
      "type": "PASSPORT",
      "number": "E98765432",
      "front_file": "<base64_encoded_image>",
      "back_file": "<base64_encoded_image>",
      "hand_file": "<base64_encoded_image>"
    },
    "residential_address": {
      "country": "SG",
      "state": "Singapore",
      "city": "Singapore",
      "district": "Buona Vista",
      "line1": "9 N Buona Vista Dr",
      "line2": "THE METROPOLIS",
      "line_en": "9 N Buona Vista Dr, THE METROPOLIS",
      "postal_code": "138666"
    },
    "kyc_verification": {
      "method": "SUMSUB_REDIRECT"
    }
  }'

响应 —— 持卡人进入 INCOMPLETE 状态，并附带一个 IDV 链接：

{
  "cardholder_id": "9d6017b2-0c2f-4b2e-876b-992b0db9597d",
  "cardholder_status": "INCOMPLETE",
  "idv_verification_url": "https://in.sumsub.com/websdk/p/sbx_MVSJTHTZj77PZggH",
  "idv_url_expires_at": "2026-04-04T17:32:50+08:00"
}

将持卡人重定向到 idv_verification_url 完成身份验证，然后等待 webhook 通知（见步骤3）。

方式 B：THIRD_PARTY

如果你已通过自有 KYC 服务商完成持卡人身份验证并有凭证引用，使用此方式。

curl -X POST "https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders" \
  -H "Content-Type: application/json" \
  -H "x-auth-token: {your_auth_token}" \
  -H "x-idempotency-key: {unique_uuid}" \
  -d '{
    "first_name": "Sarah",
    "last_name": "Chen",
    "email": "sarah.chen@example.com",
    "country_code": "SG",
    "phone_number": "90755646",
    "date_of_birth": "1992-06-15",
    "nationality": "SG",
    "identity": {
      "type": "PASSPORT",
      "number": "E98765432",
      "front_file": "<base64_encoded_image>",
      "back_file": "<base64_encoded_image>",
      "hand_file": "<base64_encoded_image>"
    },
    "residential_address": {
      "country": "SG",
      "state": "Singapore",
      "city": "Singapore",
      "district": "Buona Vista",
      "line1": "9 N Buona Vista Dr",
      "line2": "THE METROPOLIS",
      "line_en": "9 N Buona Vista Dr, THE METROPOLIS",
      "postal_code": "138666"
    },
    "kyc_verification": {
      "method": "THIRD_PARTY",
      "kyc_proof": {
        "provider": "YOUR_PROVIDER",
        "reference_id": "your_provider_ref_1234567890"
      }
    }
  }'

kyc_proof.reference_id 至少 10 个字符，全局唯一。

响应 —— 持卡人立即完成验证：

{
  "cardholder_id": "9d6017b2-0c2f-4b2e-876b-992b0db9597d",
  "cardholder_status": "SUCCESS"
}

可以直接进入步骤4：创建卡片。

步骤3：等待 KYC 审核通过（仅 SUMSUB_REDIRECT）

如果你使用了 SUMSUB_REDIRECT，订阅 cardholder.kyc.status_changed webhook 以实时接收 KYC 状态变更。 Webhook payload 示例（KYC 已通过）：

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "cardholder.kyc.status_changed",
  "event_id": "d92ab1ec-1737-4b3c-bedb-7500a3c02677",
  "source_id": "9d6017b2-0c2f-4b2e-876b-992b0db9597d",
  "data": {
    "cardholder_id": "9d6017b2-0c2f-4b2e-876b-992b0db9597d",
    "cardholder_status": "SUCCESS",
    "country_code": "SG",
    "create_time": "2026-04-03T17:32:50+08:00",
    "date_of_birth": "1992-06-15",
    "email": "sarah.chen@example.com",
    "first_name": "Sarah",
    "idv_provider": "SUMSUB",
    "idv_status": "PASSED",
    "last_name": "Chen",
    "nationality": "SG",
    "phone_number": "90755646",
    "update_time": "2026-04-03T17:34:49+08:00"
  }
}

当 cardholder_status 变为 SUCCESS 时，持卡人即可签发卡片。

持卡人处于 PENDING 状态时无法签发卡片。请先等待 KYC 审核通过。

步骤4：创建卡片

当 cardholder_status 为 SUCCESS 后，调用 Create Card：

下方示例使用沙盒环境的 card_currency: "USD"。生产环境下请将 card_currency 设置为 XUSD。

curl -X POST "https://api-sandbox.uqpaytech.com/api/v1/issuing/cards" \
  -H "Content-Type: application/json" \
  -H "x-auth-token: {your_auth_token}" \
  -H "x-idempotency-key: bf705cbd-27f0-48d1-a60b-212134a89ad7" \
  -d '{
    "cardholder_id": "9d6017b2-0c2f-4b2e-876b-992b0db9597d",
    "card_product_id": "0d8f10de-c888-4107-ab65-1cc9deb31b3b",
    "card_currency": "USD",
    "card_limit": 1000
  }'

响应：

{
  "card_id": "d26f2287-434b-41a4-af47-f06dbf6f9e71",
  "card_order_id": "c004375c-8137-4b94-b948-4282bff33625",
  "card_status": "PENDING",
  "order_status": "PROCESSING",
  "create_time": "2026-04-03T17:35:55+08:00",
  "risk_controls": {}
}

错误处理

建卡时 KYC 信息不足

如果持卡人尚未满足产品的 KYC 要求就尝试创建卡片，你会收到如下错误，其中 missing_fields 指明仍需补齐的字段：

{
  "code": "kyc_insufficient",
  "message": "Cardholder KYC information is insufficient for this product.",
  "missing_fields": ["identity", "residential_address"]
}

你可以选择：

先通过 Update Cardholder 更新持卡人信息，然后重试建卡。
在 Create Card 请求中通过 cardholder_required_fields 字段内联补充缺失的信息。

持卡人处于 PENDING 状态

持卡人 cardholder_status 为 PENDING 时创建卡片会被拒绝。请等待 KYC 审核完成后再重试。

入门

持卡人

卡片

充值

管理与安全

集成

参考

概览

前置条件

步骤1：检查产品要求

步骤2：使用 Enhanced KYC 创建持卡人

方式 A：SUMSUB_REDIRECT

方式 B：THIRD_PARTY

步骤3：等待 KYC 审核通过（仅 SUMSUB_REDIRECT）

步骤4：创建卡片

错误处理

建卡时 KYC 信息不足

持卡人处于 PENDING 状态

​概览

​前置条件

​步骤1：检查产品要求

​步骤2：使用 Enhanced KYC 创建持卡人

​方式 A：SUMSUB_REDIRECT

​方式 B：THIRD_PARTY

​步骤3：等待 KYC 审核通过（仅 SUMSUB_REDIRECT）

​步骤4：创建卡片

​错误处理

​建卡时 KYC 信息不足

​持卡人处于 PENDING 状态

概览

前置条件

步骤1：检查产品要求

步骤2：使用 Enhanced KYC 创建持卡人

方式 A：SUMSUB_REDIRECT

方式 B：THIRD_PARTY

步骤3：等待 KYC 审核通过（仅 SUMSUB_REDIRECT）

步骤4：创建卡片

错误处理

建卡时 KYC 信息不足

持卡人处于 PENDING 状态