> ## 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.

# 创建和管理持卡人

> 在签发卡片前先注册持卡人身份，并按需更新持卡人信息。

持卡人代表将使用卡片的人。向持卡人签发任何卡片之前，必须先创建持卡人。卡片一旦绑定持卡人，关联关系不可更改。

> [!NOTE]
>
> **前置条件**
>
> * 已启用 Card Issuance 的 UQPAY 账户
> * 通过 [Access Token](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/access-token.md) 接口获取的 API Token

## 创建持卡人

向 [Create Cardholder](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-cardholder.md) 接口发送 `POST` 请求，传入持卡人的身份信息。

**必填字段：**

| 字段 | 说明 |
| - | - |
| `first_name` | 持卡人名字（仅限字母、空格和连字符） |
| `last_name` | 持卡人姓氏 |
| `email` | 在同一账户下必须唯一 |
| `country_code` | 两位国家代码（ISO 3166-1 alpha-2） |
| `phone_number` | 在同一账户下必须唯一。长度按国家校验 —— 参见[手机号校验规则](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/phone-number-validation-rules-for-cardholder.md) |

**可选字段：** `date_of_birth`、`gender`、`nationality`、`residential_address`、`identity`、`kyc_verification`、`document_type`、`document`

> [!WARNING]
>
> 持卡人的 **email** 和 **phone\_number** 在同一账户下的所有持卡人中必须唯一。重复值会被拒绝。

### 请求

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Alex",
    "last_name": "Chen",
    "email": "alex.chen@example.com",
    "country_code": "SG",
    "phone_number": "91234567"
  }'
```

### 响应

```json theme={null}
{
  "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
  "cardholder_status": "SUCCESS"
}
```

结果同步返回 —— 创建持卡人不会触发 webhook。

> [!NOTE]
>
> 如果卡产品需要 Enhanced KYC，`cardholder_status` 将返回 `PENDING` 而非 `SUCCESS`。持卡人必须先完成身份验证，才能签发卡片。参见 [KYC 验证](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/enhanced-kyc-card-issuance.md) 指南。

## 持卡人状态

| 状态 | 说明 |
| - | - |
| `SUCCESS` | 持卡人已激活，可以签发卡片 |
| `PENDING` | 等待 KYC 验证 |
| `INCOMPLETE` | KYC 材料缺失或需重新提交 |
| `FAILED` | 入驻失败 |

## 查询持卡人

使用 [Retrieve Cardholder](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/retrieve-cardholder.md) 接口获取持卡人完整信息。

```bash theme={null}
curl https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders/25ea804d-7fd5-43d5-8792-0fc0214cdb2f \
  -H "x-auth-token: YOUR_API_TOKEN"
```

```json theme={null}
{
  "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
  "email": "alex.chen@example.com",
  "first_name": "Alex",
  "last_name": "Chen",
  "country_code": "SG",
  "phone_number": "91234567",
  "number_of_cards": 1,
  "cardholder_status": "SUCCESS",
  "create_time": "2026-04-10T18:03:47+08:00"
}
```

## 列出持卡人

使用 [List Cardholders](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/list-cardholders.md) 接口分页遍历所有持卡人。可以按 `cardholder_status` 过滤。

```bash theme={null}
curl "https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders?page_number=1&page_size=10" \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
```

## 更新持卡人

使用 [Update Cardholder](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/update-cardholder.md) 接口修改持卡人信息。可以更新 `email`、`phone_number`、`country_code`、`date_of_birth`、`gender`、`nationality`、`residential_address`，以及身份和 KYC 相关字段。

> [!WARNING]
>
> `first_name` 和 `last_name` 创建后无法更新。

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders/25ea804d-7fd5-43d5-8792-0fc0214cdb2f \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "SG",
    "phone_number": "98765432"
  }'
```

## 相关阅读

* [KYC 验证](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/enhanced-kyc-card-issuance.md) —— 需要身份验证的卡产品所使用的 Enhanced KYC 流程
* [手机号校验规则](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/phone-number-validation-rules-for-cardholder.md) —— 各国手机号长度要求
* [Create Cardholder API](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/create-cardholder.md)
* [持卡人 webhook](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/webhooks/cardholder-kyc-status-changed.md)


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