跳转到主要内容
持卡人代表将使用卡片的人。向持卡人签发任何卡片之前，必须先创建持卡人。卡片一旦绑定持卡人，关联关系不可更改。
前置条件
  • 已启用 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": "[email protected]",
    "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 验证
INCOMPLETEKYC 材料缺失或需重新提交
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": "[email protected]",
  "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"
  }'