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

# 创建和管理持卡人

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

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

<Info>
  **前置条件**

  * 已启用 Card Issuance 的 UQPAY 账户
  * 通过 [Access Token](/zh/account-center/v1.6/api-reference/access-token) 接口获取的 API Token
</Info>

<h2 id="create-a-cardholder">创建持卡人</h2>

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

**必填字段：**

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

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

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

<h3 id="request">请求</h3>

```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"
  }'
```

<h3 id="response">响应</h3>

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

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

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

<h2 id="cardholder-status">持卡人状态</h2>

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

<h2 id="retrieve-a-cardholder">查询持卡人</h2>

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

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

<h2 id="list-cardholders">列出持卡人</h2>

使用 [List Cardholders](/zh/card-issuance/v1.6/api-reference/list-cardholders) 接口分页遍历所有持卡人。可以按 `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"
```

<h2 id="update-a-cardholder">更新持卡人</h2>

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

<Warning>
  `first_name` 和 `last_name` 创建后无法更新。
</Warning>

```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"
  }'
```

<h2 id="related">相关阅读</h2>

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