Manage Card Status

Card Status Reference

The table below provides an overview of all possible card statuses in UQPAY, including their meaning, whether the status can be changed by the user (via API or Dashboard), and additional remarks on behavior or limitations.

This reference helps developers understand how to manage a card’s lifecycle, including how to activate, freeze, or cancel a card, and what to expect when the card transitions to a specific state.

Flowchart: Card Status

flowchart TD
    %% Node Definitions
    CARD_CREATION(("Card Creation")):::start
    PENDING["Status: PENDING"]:::intermediate
    ACTIVE["Status: ACTIVE"]:::active
    FAILED["Status: FAILED"]:::error
    FROZEN["Status: FROZEN<br/>(Declines all authorizations)"]:::warning
    BLOCKED["Status: BLOCKED"]:::error
    PRE_CANCEL["Status: PRE_CANCEL<br/>(Pre-cancellation state, cancellation waiting period)"]:::warning
    CANCELLED(("Status: CANCELLED<br/>(Card permanently cancelled)")):::error


    %% Transitions
    CARD_CREATION -- Card creation request received --> PENDING
    PENDING -->|Success<br/> Card is ready to use| ACTIVE
    PENDING -->|Failure<br/> Card creation failed| FAILED

    ACTIVE --> |Card Frozen function was triggered|FROZEN
    FROZEN --> |Card reactivated by the user| ACTIVE
    ACTIVE --> |Card Cancellation was triggered|PRE_CANCEL
    PRE_CANCEL --> |After cancellation waiting period ended| CANCELLED

    ACTIVE --> |Blocked due to suspicious activity| BLOCKED
    
    BLOCKED --> |contacted UQPAY Support, and reactivated| ACTIVE

    %% Style Definitions (placed at the end for compatibility)
    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

Webhook Notification for Card Status Updated

When a card's status transitions to ACTIVE, PRE_CANCEL, CANCELLED, FROZEN, or BLOCKED, UQPAY will automatically trigger a card.status.update webhook event. This allows your system to stay in sync with the latest card lifecycle state in near real-time.

Note: This webhook only reflects status updates after the card has been issued.
For example, it does not cover:

• The initial activation of a physical card

• The default ACTIVE status upon virtual card issuance

Notification example

{
    "version": "V1.6.0", 
    "event_name": "ISSUING", 
    "event_type": "card.status.update.succeeded", 
    "event_id": "8a78af1e-de83-43a5-b177-ecbc6a8a9fc6", 
    "source_id": "cc9b4589-58c4-4c19-b96c-5c5fac43d07d", // card_order_id
    "data": {
        "card_id": "c0cef051-29c5-47-b86a-cd5b684bfad7", 
        "card_number": "************5668", 
        "update_time": "2024-03-21T17:17:32+08:00", 
         // one of: ACTIVE, PRE_CANCEL, CANCELLED, FROZEN, BLOCKED
        "card_status": "ACTIVE"
    }
}

Refer to the Webhook: Card Status Updated section for details.

Cancel a Card

You can initiate a card cancellation via the UQPAY API or Dashboard. Once the request is submitted, the card status will first be updated to PRE_CANCEL. In this state:

• All new authorization attempts will be automatically declined.

• Authorized but unsettled transactions

  • The cancellation prevents new transactions but does not affect the settlement of previously authorized ones.

  • When a card is canceled in the presence of authorized but unsettled transactions, those transactions that have yet to be cleared will continue to be processed.

• Pending transactions

  • If there are pending transactions, canceling the card will not stop them from processing if they have already been approved.

  • Pending transactions are those that have been authorized and awaiting merchant capture or settlement; they will go through even after cancellation, as they no longer require further authorization.

• If the card holds any remaining balance, it will be automatically returned to the account balance after a waiting period (60 or 90 days). To avoid this delay, you may choose to withdraw the remaining balance manually before initiating the card cancellation.

Once the waiting period ends, the card status will be updated to CANCELLED. At this point:

• The card is permanently deactivated and will no longer accept any authorization requests.

• For single cards, the remaining balance is returned automatically.

• For shared cards, no refund is required, as no funds were ever transferred into the card when it was created.

⚠️

This action is irreversible. A cancelled card cannot be reactivated.

To cancel a card, call the Update Card Status endpoint with the relevant card_id and set the card_status to CANCELLED.

{
  "card_status": "CANCELLED"
}

{
  "card_id": "c0cef051-29c5-4796-b86a-cd5b684bfad7",
  "card_order_id": "c0cef051-29c5-4796-b86a-cd5ee34bfad7",
  "order_status": "PENDING"
}

You will receive a PRE_CANCEL card.status.update.succeeded webhook after the cancellation request is submitted.

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.status.update.succeeded",
  "event_id": "2f756ee0-07bc-4064-8cf8-da966b3188a8",
  "source_id": "e68fa686-6ebc-42ae-b171-6e32e0f884b5",
  "data": {
    "card_id": "4a3dc8a6-7cac-4a64-8ebc-e15cfe765e7b",
    "card_number": "46119903****7297",
    "card_status": "PRE_CANCEL",
    "update_time": "2025-07-21T21:01:06+08:00"
  }
}

Once the cancellation is fully completed, a CANCELLED card.status.update.succeeded webhook will be triggered.

{
    "version": "V1.6.0",
    "event_name": "ISSUING",
    "event_type": "card.status.update.succeeded",
    "event_id": "b44a6c45-62bd-41e2-9f50-2e0fac2606e8",
    "source_id": "e68fa686-6ebc-42ae-b171-6e32e0f884b5",
    "data": {
        "card_id": "4a3dc8a6-7cac-4a64-8ebc-e15cfe765e7b",
        "card_number": "46119903****7297",
        "card_status": "CANCELLED",
        "update_time": "2025-07-21T21:04:06+08:00"
    }
}

Freeze a Card

Freezing a card will temporarily disable all transactions. All incoming authorization requests will be declined.

This action is reversible. You can unfreeze the card at any time by reactivating it via API or Dashboard.

To freeze a card, call the Update Card Status endpoint with the relevant card_id and set the card_status to FROZEN.

{
  "card_status": "FROZEN"
}

{
  "card_id": "c0cef051-29c5-4796-b86a-cd5b684bfad7",
  "card_order_id": "c0cef051-29c5-4796-b86a-cd5ee34bfad7",
  "order_status": "PENDING"
}

Once the freeze is fully completed, a FROZEN card.status.update.succeeded webhook will be triggered.

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

To unfreeze a card, use the same endpoint and setcard_status to ACTIVE.

Related API

• Update Card Status

• Retrieve Card

• Webhook - card.status.update