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

# Card lifecycle

> Manage card status transitions — freeze, unfreeze, and cancel cards through the API.

Every card follows a lifecycle from creation to cancellation. You manage transitions through the [Update Card Status](/card-issuance/v1.6/api-reference/update-card-status) endpoint.

## Status reference

| Status       | Description                                          |
| ------------ | ---------------------------------------------------- |
| `PENDING`    | Card creation request received and processing        |
| `ACTIVE`     | Card is ready for transactions                       |
| `FROZEN`     | All authorizations declined; card can be reactivated |
| `BLOCKED`    | Blocked by UQPAY due to suspicious activity          |
| `PRE_CANCEL` | Pre-cancellation state; authorizations declined      |
| `CANCELLED`  | Permanently deactivated                              |
| `FAILED`     | Card creation failed                                 |

## Status flow

```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
```

## Freeze a card

Freezing temporarily disables all transactions. All incoming authorizations are declined until the card is unfrozen.

```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"}'
```

**Response:**

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

A `card.status.update.succeeded` webhook fires once the freeze is applied:

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

## Unfreeze a card

To reactivate a frozen card, set the status back to `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"}'
```

## Cancel a card

<Warning>
  Cancellation is irreversible. A cancelled card cannot be reactivated.
</Warning>

Set the card status to `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"}'
```

The card first transitions to `PRE_CANCEL`:

* All new authorizations are declined.
* Previously authorized but unsettled transactions continue to settle normally.
* After a 30-day waiting period, the card moves to `CANCELLED`.

### Balance handling on cancellation

| Card mode  | What happens to remaining balance                                                           |
| ---------- | ------------------------------------------------------------------------------------------- |
| **Single** | Remaining balance is returned to the issuing balance automatically after the waiting period |
| **Share**  | No refund needed — no funds were transferred into the card                                  |

<Tip>
  To avoid the 30-day wait, withdraw the remaining balance before cancelling the card using the [Card Withdraw](/card-issuance/v1.6/api-reference/card-withdraw) endpoint.
</Tip>

### Webhook sequence

1. `card.status.update.succeeded` with `card_status: PRE_CANCEL` — immediately after the cancel request
2. `card.status.update.succeeded` with `card_status: CANCELLED` — after the waiting period ends

## Webhooks

Status transitions trigger a `card.status.update.succeeded` webhook for these statuses: `ACTIVE`, `FROZEN`, `BLOCKED`, `PRE_CANCEL`, `CANCELLED`.

This webhook does **not** fire for the initial activation of a physical card or the default `ACTIVE` status when a virtual card is issued. Those are covered by the [Card Created](/card-issuance/v1.6/webhooks/card-created) and [Activation Status](/card-issuance/v1.6/webhooks/activation-status) webhooks respectively.

## Related

* [Update Card Status API](/card-issuance/v1.6/api-reference/update-card-status)
* [Card Status Updated webhook](/card-issuance/v1.6/webhooks/card-status-updated)
* [Core concepts](/card-issuance/v1.6/guide/core-concepts) — Single vs. Share mode cancellation differences