创建和管理持卡人

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

前置条件

已启用 Card Issuance 的 UQPAY 账户
通过 Access Token 接口获取的 API Token

创建持卡人

向 Create Cardholder 接口发送 POST 请求，传入持卡人的身份信息。 必填字段：

字段	说明
`first_name`	持卡人名字（仅限字母、空格和连字符）
`last_name`	持卡人姓氏
`email`	在同一账户下必须唯一
`country_code`	两位国家代码（ISO 3166-1 alpha-2）
`phone_number`	在同一账户下必须唯一。长度按国家校验 —— 参见手机号校验规则

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

持卡人的 email 和 phone_number 在同一账户下的所有持卡人中必须唯一。重复值会被拒绝。

请求

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

响应

{
  "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
  "cardholder_status": "SUCCESS"
}

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

如果卡产品需要 Enhanced KYC，cardholder_status 将返回 PENDING 而非 SUCCESS。持卡人必须先完成身份验证，才能签发卡片。参见 KYC 验证指南。

持卡人状态

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

查询持卡人

使用 Retrieve Cardholder 接口获取持卡人完整信息。

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

{
  "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 接口分页遍历所有持卡人。可以按 cardholder_status 过滤。

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 接口修改持卡人信息。可以更新 email、phone_number、country_code、date_of_birth、gender、nationality、residential_address，以及身份和 KYC 相关字段。

first_name 和 last_name 创建后无法更新。

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 验证 —— 需要身份验证的卡产品所使用的 Enhanced KYC 流程
手机号校验规则 —— 各国手机号长度要求
Create Cardholder API
持卡人 webhook

入门

持卡人

卡片

充值

管理与安全

集成

参考

创建持卡人

请求

响应

持卡人状态

查询持卡人

列出持卡人

更新持卡人

​创建持卡人

​请求

​响应

​持卡人状态

​查询持卡人

​列出持卡人

​更新持卡人

​相关阅读

创建持卡人

请求

响应

持卡人状态

查询持卡人

列出持卡人

更新持卡人

相关阅读