> ## 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 管理卡状态变更 —— 冻结、解除冻结和注销卡片。

每张卡都遵循从创建到注销的生命周期。你可以通过 [Update Card Status](/zh/card-issuance/v1.6/api-reference/update-card-status) 接口管理状态变更。

<h2 id="status-reference">状态参考</h2>

| 状态           | 说明                |
| ------------ | ----------------- |
| `PENDING`    | 卡片创建请求已受理，正在处理中   |
| `ACTIVE`     | 卡片可用于交易           |
| `FROZEN`     | 所有授权都会被拒绝；卡片可重新激活 |
| `BLOCKED`    | 因可疑活动被 UQPAY 锁定   |
| `PRE_CANCEL` | 预注销状态；授权被拒绝       |
| `CANCELLED`  | 已永久停用             |
| `FAILED`     | 卡片创建失败            |

<h2 id="status-flow">状态流转</h2>

```mermaid theme={null}
flowchart TD
    CREATION(("Card Creation")):::start
    PENDING["PENDING"]:::intermediate
    ACTIVE["ACTIVE"]:::active
    FAILED["FAILED"]:::error
    FROZEN["FROZEN"]:::warning
    BLOCKED["BLOCKED"]:::error
    PRE_CANCEL["PRE_CANCEL"]:::warning
    CANCELLED(("CANCELLED")):::error

    CREATION -- Request received --> PENDING
    PENDING -->|Success| ACTIVE
    PENDING -->|Failure| FAILED

    ACTIVE -->|Freeze| FROZEN
    FROZEN -->|Unfreeze| ACTIVE
    ACTIVE -->|Cancel| PRE_CANCEL
    PRE_CANCEL -->|Waiting period ended| CANCELLED

    ACTIVE -->|Suspicious activity| BLOCKED
    BLOCKED -->|UQPAY support| ACTIVE

    classDef start fill:#E0E0E0,stroke:#999999,color:#000000
    classDef active fill:#B8E986,stroke:#5A8F00,color:#000000
    classDef intermediate fill:#D9EFFF,stroke:#3399FF,color:#000000
    classDef warning fill:#FFF3B0,stroke:#E0B400,color:#000000
    classDef error fill:#FFB3B3,stroke:#D20000,color:#000000
```

<h2 id="freeze-a-card">冻结卡片</h2>

冻结会临时禁用所有交易。在卡片被解除冻结之前，所有到达的授权请求都会被拒绝。

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id}/status \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{"card_status": "FROZEN"}'
```

**响应：**

```json theme={null}
{
  "card_id": "c0cef051-29c5-4796-b86a-cd5b684bfad7",
  "card_order_id": "c0cef051-29c5-4796-b86a-cd5ee34bfad7",
  "order_status": "PENDING"
}
```

冻结生效后，会触发一次 `card.status.update.succeeded` webhook：

```json theme={null}
{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.status.update.succeeded",
  "event_id": "54daa345-889a-4488-9002-935f63b7d3c9",
  "source_id": "3f3d036e-732c-4f9e-a4b7-3019c0adf749",
  "data": {
    "card_id": "3974bad1-247b-4939-8965-3223182fba1f",
    "card_number": "46119903****1244",
    "card_status": "FROZEN",
    "update_time": "2025-07-21T21:11:06+08:00"
  }
}
```

<h2 id="unfreeze-a-card">解除冻结</h2>

要重新激活一张已冻结的卡片，把状态改回 `ACTIVE`：

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id}/status \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{"card_status": "ACTIVE"}'
```

<h2 id="cancel-a-card">注销卡片</h2>

<Warning>
  注销不可逆，已注销的卡片无法重新激活。
</Warning>

把卡片状态改为 `CANCELLED`：

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards/{card_id}/status \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{"card_status": "CANCELLED"}'
```

卡片首先会进入 `PRE_CANCEL` 状态：

* 所有新的授权请求都会被拒绝。
* 此前已授权但尚未结算的交易会正常完成结算。
* 经过 30 天等待期后，卡片进入 `CANCELLED` 状态。

<h3 id="balance-handling-on-cancellation">注销时的余额处理</h3>

| 卡模式        | 剩余余额的处理方式             |
| ---------- | --------------------- |
| **Single** | 等待期结束后，剩余余额自动退回发卡账户余额 |
| **Share**  | 无需退款 —— 没有资金转入过卡片     |

<Tip>
  如要避免 30 天等待期，可以在注销卡片前，通过 [Card Withdraw](/zh/card-issuance/v1.6/api-reference/card-withdraw) 接口先把剩余余额提取出来。
</Tip>

<h3 id="webhook-sequence">Webhook 顺序</h3>

1. `card.status.update.succeeded`，`card_status: PRE_CANCEL` —— 注销请求发出后立即触发
2. `card.status.update.succeeded`，`card_status: CANCELLED` —— 等待期结束后触发

<h2 id="webhooks">Webhook</h2>

以下状态变更会触发 `card.status.update.succeeded` webhook：`ACTIVE`、`FROZEN`、`BLOCKED`、`PRE_CANCEL`、`CANCELLED`。

该 webhook **不会**在实体卡首次激活或虚拟卡签发默认进入 `ACTIVE` 状态时触发 —— 这两种场景分别由 [Card Created](/zh/card-issuance/v1.6/webhooks/card-created) 和 [Activation Status](/zh/card-issuance/v1.6/webhooks/activation-status) webhook 覆盖。

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

* [Update Card Status API](/zh/card-issuance/v1.6/api-reference/update-card-status)
* [Card Status Updated webhook](/zh/card-issuance/v1.6/webhooks/card-status-updated)
* [核心概念](/zh/card-issuance/v1.6/guide/core-concepts) —— Single 与 Share 模式注销时的差异