> ## 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>
  **前置条件**

  * 一位 `cardholder_status: SUCCESS` 的持卡人 —— 参见[创建持卡人](/zh/card-issuance/v1.6/guide/create-and-manage-cardholders)
  * 一个实体卡卡号（由 UQPAY 作为你卡片库存的一部分提供）
  * 如果使用 Single mode 产品，需要有充足的发卡账户余额
</Info>

<h2 id="step-1-assign-the-card">步骤1：绑定卡片</h2>

调用 [Assign Card](/zh/card-issuance/v1.6/api-reference/assign-card) 接口，把一张实体卡关联到持卡人。

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/assign \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "cardholder_id": "4438b25d-caa7-4dcf-a8e0-970f05a7bf31",
    "card_number": "4096360800121514",
    "card_currency": "SGD",
    "card_mode": "SINGLE"
  }'
```

**响应：**

```json theme={null}
{
  "card_order_id": "07ad04df-39dd-44a1-bbc5-15b2eff6f709",
  "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
  "card_status": "PENDING",
  "order_status": "PENDING",
  "create_time": "2025-07-27T21:00:05+08:00",
  "risk_controls": {}
}
```

绑定完成后会发生两件事：

1. `card.activation.code` webhook 会下发激活码。
2. `card.create.succeeded` webhook 确认卡片已绑定。卡片会保持 `PENDING` 状态，直到被激活。

系统同时会发送一封包含激活码的邮件通知（可配置 —— 可以发给持卡人或你的机构邮箱，也可以关闭）。

<Note>
  激活码不会过期。
</Note>

<h2 id="step-2-receive-the-activation-code">步骤2：接收激活码</h2>

订阅 `card.activation.code` webhook，即可以编程方式接收激活码。

```json theme={null}
{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.activation.code",
  "event_id": "759e6599-d3cc-415e-94e7-dfdd5d3401d1",
  "source_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
  "data": {
    "activation_code": "81534005",
    "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
    "card_number": "40963608****1514"
  }
}
```

<h2 id="step-3-activate-the-card">步骤3：激活卡片</h2>

使用激活码和一个 6 位 PIN 码，调用 [Activate Card](/zh/card-issuance/v1.6/api-reference/activate-card) 接口。

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/activate \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
    "activation_code": "81534005",
    "pin": "123456"
  }'
```

<Warning>
  PIN 码必须**正好 6 位数字**。
</Warning>

激活成功后，会触发一次 `card.activation.status` webhook，并发送一封邮件确认。

```json theme={null}
{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.activation.status",
  "event_id": "bd0a312b-25a3-46aa-b553-6b360d3a6ba7",
  "source_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
  "data": {
    "activation_status": "Activated",
    "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
    "card_number": "40963608****1514"
  }
}
```

卡片状态从 `PENDING` 变更为 `ACTIVE`。此时卡片已可用于交易，包括 ATM 取现（仅限支持的 BIN）。

<h2 id="reset-pin">重置 PIN 码</h2>

你可以随时通过 [Reset Card PIN](/zh/card-issuance/v1.6/api-reference/reset-pin) 接口修改卡片的 PIN 码。结果同步返回 —— 不会触发 webhook。

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/pin \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
    "pin": "654321"
  }'
```

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

* [核心概念](/zh/card-issuance/v1.6/guide/core-concepts) —— 虚拟卡与实体卡、Single 与 Share
* [卡生命周期](/zh/card-issuance/v1.6/guide/card-lifecycle) —— 冻结、解除冻结或注销卡片
* [Assign Card API](/zh/card-issuance/v1.6/api-reference/assign-card)
* [Activate Card API](/zh/card-issuance/v1.6/api-reference/activate-card)
* [Activation Code webhook](/zh/card-issuance/v1.6/webhooks/activation-code)
* [Activation Status webhook](/zh/card-issuance/v1.6/webhooks/activation-status)