跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt

Use this file to discover all available pages before exploring further.

常规开卡流程分两步：先调 创建持卡人，再用返回的 cardholder_id 调 创建卡片。一步开卡模式把两步合成一次调用——不再传 cardholder_id，而是把持卡人资料放在 cardholder_required_fields 里，系统在同一笔请求中建好持卡人并开卡。 适合”用户一注册就发卡”、“单屏完成开卡”这类按需开卡的场景。如果你已经有一批预建好的持卡人要复用，继续用两步的传统流程即可——传 cardholder_id 的调用方式完全不变。

​
前置条件

​
第一步：查产品，确认需要哪些字段

不同卡产品（BIN）对持卡人资料的要求不同。先调卡产品列表，拿到目标产品的 required_fields 数组——这就是你需要在开卡接口里上送的持卡人字段清单。 
curl "https://api-sandbox.uqpaytech.com/api/v1/issuing/products?page_number=1&page_size=10" \
  -H "x-auth-token: Bearer {your_auth_token}"
响应片段（只保留关键字段）： 
{
  "product_id": "467e993f-317a-49fc-9ea0-bf49de7d1f76",
  "card_bin": "40963608",
  "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": "phone_number",  "type": "string", "required": true },
    { "name": "date_of_birth", "type": "string", "required": false }
  ]
}
required: true 的字段必须提供；required: false 的字段可选。type: object 的字段（如 identity、residential_address、kyc_verification）需按嵌套结构填写，子字段规则由产品的 fields 数组给出。

​
第二步：调开卡接口，把字段一并上送

把产品要求的字段放进 cardholder_required_fields，不传 cardholder_id： 
curl -X POST "https://api-sandbox.uqpaytech.com/api/v1/issuing/cards" \
  -H "Content-Type: application/json" \
  -H "x-auth-token: Bearer {your_auth_token}" \
  -H "x-idempotency-key: {unique_uuid}" \
  -d '{
    "card_product_id": "467e993f-317a-49fc-9ea0-bf49de7d1f76",
    "card_currency": "USD",
    "card_limit": "500.00",
    "cardholder_required_fields": {
      "email": "[email protected]",
      "first_name": "Alex",
      "last_name": "Chen",
      "country_code": "SG",
      "phone_number": "90851548"
    }
  }'
响应： 
{
  "card_order_id": "86411dab-9820-4042-b103-39989deb957d",
  "card_id": "b52e93a8-3c1d-453e-81ac-ec7268fad082",
  "cardholder_id": "a32835fe-141e-41fd-bcce-9fe88b3e8cbd",
  "card_status": "PENDING",
  "order_status": "PROCESSING",
  "create_time": "2026-04-24T18:07:49+08:00",
  "cardholder_status": "SUCCESS",
  "cardholder_created": true,
  "verification_status": "VERIFIED",
  "message": "card creation in progress"
}
几个关键字段：
  • cardholder_id——这一步新建的持卡人 ID，保存下来供后续管理持卡人使用。
  • card_status: PENDING + order_status: PROCESSING——卡正在异步发卡。不代表失败，等 card.create.succeeded webhook 才算发卡完成。
  • cardholder_created: true——持卡人是本次调用新建的。

​
特殊情况：需要 Sumsub IDV 时

如果产品的 required_fields 要求 kyc_verification，并且你让 UQPAY 走 Sumsub 完成身份验证（method: SUMSUB_REDIRECT），响应会多出 IDV 链接： 
{
  "card_id": "ef5c44df-8c31-4adf-88b2-22ff7ce0e6d8",
  "cardholder_id": "9cb41553-e186-4e43-a17a-07f0772c6c75",
  "card_status": "PENDING",
  "cardholder_status": "INCOMPLETE",
  "idv_verification_url": "https://in.sumsub.com/websdk/p/sbx_xxx",
  "idv_url_expires_at": "2026-04-25T18:09:19+08:00",
  "kyc_method": "SUMSUB_REDIRECT",
  "verification_status": "ACTION_REQUIRED"
}
把持卡人重定向到 idv_verification_url（需在 idv_url_expires_at 之前完成）。Sumsub 核验通过后，UQPAY 会自动激活卡片，并通过 webhook 通知你。 若你自己完成了 KYC 并想直接提交证明，用 method: THIRD_PARTY + kyc_proof，接口会直接返回 verification_status: VERIFIED，不需要再重定向。详细规则见 Enhanced KYC 开卡指南。

​
等待异步完成

对所有一步开卡请求，初次 HTTP 响应只是”已受理”。卡的真正激活（和持卡人最终状态）走异步，订阅这两个 webhook： 在调用开卡接口之前先把 webhook 订阅好，否则会漏掉状态变更。

​
错误处理

两个一步开卡模式特有的错误，均返回 HTTP 400：

​
cardholder_missing_info

请求里既没传 cardholder_id、也没传 cardholder_required_fields。 
{
  "type": "cardholder_error",
  "code": "cardholder_missing_info",
  "message": "either cardholder_id or complete cardholder_required_fields must be provided"
}

​
cardholder_incomplete_fields

传了 cardholder_required_fields，但缺关键字段（比如 email、first_name 等）。响应会附带 missing_fields 数组告诉你具体少了哪些，可以用来在前端给用户做精确提示。 
{
  "type": "cardholder_error",
  "code": "cardholder_incomplete_fields",
  "message": "cardholder_required_fields is incomplete for one-step card issuance",
  "missing_fields": ["email", "first_name", "last_name", "country_code"]
}
其他常见错误（email_duplicated、phone_number_duplicated、invalid_phone_number 等）沿用现有 cardholder_error 错误码，完整列表见 Create Card API 参考。