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

# Enhanced KYC 发卡流程

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

[仅 Personal Visa](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/card-products.md)

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

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

> [!WARNING]
>
> **Personal Visa 开卡受持卡人地区限制。** 持卡人的 `residential_address.country` 和 `nationality` 决定其是否具备开卡资格。若居住国家/地区不受支持或国籍受限制，Create Card 请求将被拒绝。建议在创建持卡人并发起 KYC 前，先查看完整的[持卡人地区限制](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/cardholder-region-restrictions.md)，避免完成 KYC 后仍无法开卡。

> [!NOTE]
>
> **持卡人要求**
>
> * 调用 [List Products](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/list-card-products.md)，并以目标产品的 `required_fields` 为准。Enhanced KYC 产品要求提供 `identity`、`residential_address` 和 `kyc_verification`；如果产品只要求 Simplified KYC 字段，现有的持卡人创建流程无需改动。
> * `first_name` 与 `last_name` 的总长度不能超过 26 个字母。
> * `residential_address.postal_code` 长度必须为 4–10 位（含两端）。

## 概览

```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: 卡片已创建
```

## 前置条件

调用 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`。

## 步骤1：检查产品要求

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

```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 }
          ]
        }
      ]
    }
  ]
}
```

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

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

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

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

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

### 方式 A：SUMSUB\_REDIRECT

如果你希望 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)）。

### 方式 B：THIRD\_PARTY

如果你已通过自有 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": "<reference_id>"
      }
    }
  }'
```

将 `<reference_id>` 替换为 KYC 服务商提供的全局唯一引用 ID。`kyc_proof.reference_id` 长度须为 10–64 个字符，包含两端。

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

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

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

## 步骤3：等待 KYC 审核通过（仅 SUMSUB\_REDIRECT）

如果你使用了 `SUMSUB_REDIRECT`，订阅 [`cardholder.kyc.status_changed`](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/webhooks/cardholder-kyc-status-changed) webhook，在 KYC 审核完成或需要补充资料时接收通知。根据 `data.cardholder_status` 处理结果：

* `SUCCESS`：审核通过，可以继续发卡。
* `FAILED`：审核被拒绝，请勿发卡。
* `INCOMPLETE`：需要补充或更正资料。处理资料要求后，等待状态变为 `SUCCESS` 再发卡。

审核后需要补充资料时也使用此事件。`data.reason` 在有可用拒绝或补充资料说明时包含该说明，无可用说明或审核通过时为空；请勿仅凭说明为空判断审核通过。

**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` 时，持卡人即可签发卡片。

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

## 步骤4：创建卡片

当 `cardholder_status` 为 `SUCCESS` 后，调用 [Create Card](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-card.md)：

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

```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": {}
}
```

## 错误处理

### 建卡时 KYC 信息不足

如果持卡人尚未满足产品的 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](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/update-cardholder.md) 更新持卡人信息，然后重试建卡。
2. 在 Create Card 请求中通过 `cardholder_required_fields` 字段内联补充缺失的信息。

### 持卡人处于 PENDING 状态

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.