> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enhanced KYC 发卡流程

> 签发需要 Enhanced KYC 验证的卡片的完整分步指南。

部分卡产品（按 BIN 区分）要求持卡人先完成 **Enhanced KYC** —— 即通过第三方服务商完成身份验证 —— 才能签发卡片。本指南涵盖从检查产品要求到成功签发卡片的完整流程。

<Callout icon="💡" theme="info">
  如果你的卡产品只需要基础字段（Simplified KYC），现有的持卡人创建流程可以照常使用，无需改动。通过 [List Products](/zh/card-issuance/v1.6/api-reference/list-card-products) 查询产品要求的字段。
</Callout>

<h2 id="overview">概览</h2>

```mermaid theme={null}
sequenceDiagram
    participant M as 商户
    participant U as UQPAY API
    participant S as Sumsub (IDV)

    M->>U: 1. GET /v1/issuing/products
    U-->>M: 每个产品的 required_fields

    M->>U: 2. POST /v1/issuing/cardholders（含 KYC 字段）
    alt THIRD_PARTY method
        U-->>M: cardholder_status: SUCCESS
    else SUMSUB_REDIRECT method
        U-->>M: cardholder_status: INCOMPLETE + idv_verification_url
        M->>S: 3. 将持卡人重定向到 IDV URL
        S-->>U: IDV 回调
        U-->>M: Webhook: cardholder.kyc.status_changed
    end

    M->>U: 4. POST /v1/issuing/cards
    U-->>M: 卡片已创建
```

<h2 id="prerequisites">前置条件</h2>

调用 API 之前，先获取 Access Token：

```bash theme={null}
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}"
```

```json theme={null}
{
  "auth_token": "eyJhbGciOiJIUzI1NiIs...",
  "expired_at": 1775210493
}
```

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

<h2 id="step-1-check-product-requirements">步骤1：检查产品要求</h2>

调用 [List Products](/zh/card-issuance/v1.6/api-reference/list-card-products) 查看目标产品要求哪些字段。

```bash theme={null}
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`）：

```json theme={null}
{
  "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 }
          ]
        }
      ]
    }
  ]
}
```

<Callout icon="💡" theme="info">
  `required_fields` 告诉你具体需要哪些信息。只有标注 `"required": true` 的字段是必填的 —— 可选字段可以省略。
</Callout>

<h2 id="step-2-create-cardholder-with-enhanced-kyc">步骤2：使用 Enhanced KYC 创建持卡人</h2>

调用 [Create Cardholder](/zh/card-issuance/v1.6/api-reference/create-cardholder)，传入完整的必填字段以及 `kyc_verification`。

<Callout icon="⚠️" theme="warn">
  `residential_address.country` 和 `nationality` 字段受地区限制约束。支持的国家和受制裁的国籍清单参见 [持卡人地区限制](/zh/card-issuance/v1.6/guide/cardholder-region-restrictions)。
</Callout>

<Note>
  Enhanced 卡的字段限制：

  * `first_name` 与 `last_name` 的总长度不能超过 26 个字母。
  * `residential_address.postal_code` 长度必须为 4–10 位（含两端）。
</Note>

共有两种验证方式，根据你的场景选择：

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

<h3 id="option-a-sumsub_redirect">方式 A：SUMSUB\_REDIRECT</h3>

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

```bash theme={null}
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 链接：

```json theme={null}
{
  "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](#step-3-wait-for-kyc-approval-sumsub_redirect-only)）。

<h3 id="option-b-third_party">方式 B：THIRD\_PARTY</h3>

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

```bash theme={null}
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",
        "documents": [
          { "file_id": "b3d9d2d5-4c12-4946-a09d-953e82sed2b0", "report_type": "IDV" },
          { "file_id": "7c4ff2cd-1bf6-4aaa-bf16-266771425011", "report_type": "AML" }
        ]
      }
    }
  }'
```

<Callout icon="📌" theme="info">
  `kyc_proof.reference_id` 至少 10 个字符，全局唯一。
</Callout>

### 附上合规报告

`kyc_proof.documents` 承载第三方验证背后的合规报告文件。先用 [上传文件](/zh/account-center/v1.6/api-reference/upload-file) 上传每个文件拿到 `file_id`，再在这里通过 `report_type` 引用它。

必须包含一份身份验证报告；反洗钱报告为可选。根据你的服务商出具报告的方式，有两种上送方式：

| 上送方式 | `documents` 条目                                                       |
| ---- | -------------------------------------------------------------------- |
| 分开上送 | 一条 `{ "report_type": "IDV" }`，**外加**一条可选的 `{ "report_type": "AML" }` |
| 合并上送 | 一条 `{ "report_type": "IDV_AML" }` 同时覆盖两者                             |

| `report_type` | 含义                 | 是否必填                  |
| ------------- | ------------------ | --------------------- |
| `IDV`         | 仅身份验证报告            | 是（除非以 `IDV_AML` 形式上送） |
| `AML`         | 仅反洗钱筛查报告           | 否                     |
| `IDV_AML`     | 一份文件同时覆盖 IDV 与 AML | 可满足 IDV 必填要求          |

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

```json theme={null}
{
  "cardholder_id": "9d6017b2-0c2f-4b2e-876b-992b0db9597d",
  "cardholder_status": "SUCCESS"
}
```

可以直接进入[步骤4：创建卡片](#step-4-create-card)。

<h2 id="step-3-wait-for-kyc-approval-sumsub_redirect-only">步骤3：等待 KYC 审核通过（仅 SUMSUB\_REDIRECT）</h2>

如果你使用了 `SUMSUB_REDIRECT`，订阅 `cardholder.kyc.status_changed` webhook 以实时接收 KYC 状态变更。

**Webhook payload 示例**（KYC 已通过）：

```json theme={null}
{
  "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` 时，持卡人即可签发卡片。

<Callout icon="⚠️" theme="warn">
  持卡人处于 `PENDING` 状态时无法签发卡片。请先等待 KYC 审核通过。
</Callout>

<h2 id="step-4-create-card">步骤4：创建卡片</h2>

当 `cardholder_status` 为 `SUCCESS` 后，调用 [Create Card](/zh/card-issuance/v1.6/api-reference/create-card)：

<Callout icon="📌" theme="info">
  下方示例使用沙盒环境的 `card_currency: "USD"`。生产环境下请将 `card_currency` 设置为 `XUSD`。
</Callout>

```bash theme={null}
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
  }'
```

**响应：**

```json theme={null}
{
  "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": {}
}
```

<h2 id="error-handling">错误处理</h2>

<h3 id="kyc-insufficient-at-card-creation">建卡时 KYC 信息不足</h3>

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

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

你可以选择：

1. 先通过 [Update Cardholder](/zh/card-issuance/v1.6/api-reference/update-cardholder) 更新持卡人信息，然后重试建卡。
2. 在 Create Card 请求中通过 `cardholder_required_fields` 字段内联补充缺失的信息。

<h3 id="cardholder-in-pending-status">持卡人处于 PENDING 状态</h3>

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