> ## Documentation Index
> Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 签发实体卡

> 将预制的实体卡绑定给持卡人并激活后使用。

实体卡是预制好并寄送给你或你的持卡人的卡片。与虚拟卡不同，每张实体卡必须先**绑定**给一位持卡人，然后**激活**之后才能用于交易。

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

## 步骤1：绑定卡片

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

```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]
>
> 激活码不会过期。

## 步骤2：接收激活码

订阅 `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"
  }
}
```

## 步骤3：激活卡片

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

```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 位数字**。

激活成功后，会触发一次 `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）。

## 重置 PIN 码

通过[管理卡片 PIN](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/reset-pin.md) 修改 PIN。不传 `type` 时默认为 `SET`，按首次设置 PIN 处理。如需在不提供旧 PIN 的情况下重置已有 PIN，必须显式传入 `type: RESET`。响应仅表示异步受理；使用 `card_order_id` 通过订单查询或卡更新 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",
    "type": "RESET"
  }'
```

## 相关链接

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.