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

# 一步开卡

> 在一次 API 调用中同时创建持卡人并开卡。

常规开卡流程分两步：先调 [创建持卡人](/zh/card-issuance/v1.6/api-reference/create-cardholder)，再用返回的 `cardholder_id` 调 [创建卡片](/zh/card-issuance/v1.6/api-reference/create-card)。一步开卡模式把两步合成一次调用——不再传 `cardholder_id`，而是把持卡人资料放在 `cardholder_required_fields` 里，系统在同一笔请求中建好持卡人并开卡。

适合"用户一注册就发卡"、"单屏完成开卡"这类按需开卡的场景。如果你已经有一批预建好的持卡人要复用，继续用两步的传统流程即可——传 `cardholder_id` 的调用方式完全不变。

<h2 id="prerequisites">前置条件</h2>

<Info>
  * 已启用 Card Issuance 的 UQPAY 沙盒账号
  * 通过 [获取 Access Token](/zh/account-center/v1.6/api-reference/access-token) 拿到 API token
  * 目标卡产品的 `card_product_id`——通过 [查询卡产品列表](/zh/card-issuance/v1.6/api-reference/list-card-products) 获取
</Info>

<h2 id="step-1-check-which-fields-the-product-requires">第一步：查产品，确认需要哪些字段</h2>

不同卡产品（BIN）对持卡人资料的要求不同。先调卡产品列表，拿到目标产品的 `required_fields` 数组——这就是你需要在开卡接口里上送的持卡人字段清单。

```bash theme={null}
curl "https://api-sandbox.uqpaytech.com/api/v1/issuing/products?page_number=1&page_size=10" \
  -H "x-auth-token: Bearer {your_auth_token}"
```

**响应片段（只保留关键字段）：**

```json theme={null}
{
  "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` 数组给出。

<h2 id="step-2-create-the-card-with-cardholder-data-inline">第二步：调开卡接口，把字段一并上送</h2>

把产品要求的字段放进 `cardholder_required_fields`，不传 `cardholder_id`：

```bash theme={null}
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": "alex.chen@example.com",
      "first_name": "Alex",
      "last_name": "Chen",
      "country_code": "SG",
      "phone_number": "90851548"
    }
  }'
```

**响应：**

```json theme={null}
{
  "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](/zh/card-issuance/v1.6/webhooks/card-created) webhook 才算发卡完成。
* `cardholder_created: true`——持卡人是本次调用新建的。

<h2 id="special-case-sumsub-idv">特殊情况：需要 Sumsub IDV 时</h2>

如果产品的 `required_fields` 要求 `kyc_verification`，并且你让 UQPAY 走 Sumsub 完成身份验证（`method: SUMSUB_REDIRECT`），响应会多出 IDV 链接：

```json theme={null}
{
  "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 开卡指南](/zh/card-issuance/v1.6/guide/enhanced-kyc-card-issuance)。

<h2 id="waiting-for-async-completion">等待异步完成</h2>

对所有一步开卡请求，初次 HTTP 响应只是"已受理"。卡的真正激活（和持卡人最终状态）走异步，订阅这两个 webhook：

* [Cardholder KYC Status Changed](/zh/card-issuance/v1.6/webhooks/cardholder-kyc-status-changed)——持卡人 KYC 审核完成
* [Card Created](/zh/card-issuance/v1.6/webhooks/card-created)——卡片最终激活或失败

在调用开卡接口之前先把 webhook 订阅好，否则会漏掉状态变更。

<h2 id="error-handling">错误处理</h2>

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

<h3 id="cardholder_missing_info">`cardholder_missing_info`</h3>

请求里既没传 `cardholder_id`、也没传 `cardholder_required_fields`。

```json theme={null}
{
  "type": "cardholder_error",
  "code": "cardholder_missing_info",
  "message": "either cardholder_id or complete cardholder_required_fields must be provided"
}
```

<h3 id="cardholder_incomplete_fields">`cardholder_incomplete_fields`</h3>

传了 `cardholder_required_fields`，但缺关键字段（比如 `email`、`first_name` 等）。响应会附带 `missing_fields` 数组告诉你具体少了哪些，可以用来在前端给用户做精确提示。

```json theme={null}
{
  "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 参考](/zh/card-issuance/v1.6/api-reference/create-card)。

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

* [Create Card API 参考](/zh/card-issuance/v1.6/api-reference/create-card)
* [创建与管理持卡人](/zh/card-issuance/v1.6/guide/create-and-manage-cardholders)
* [Enhanced KYC 开卡指南](/zh/card-issuance/v1.6/guide/enhanced-kyc-card-issuance)