Card Status Lifecycle — PowerUp Card Program

Overview

This document describes the complete card status lifecycle for the PowerUp Card Program, including supported statuses, creation behavior, and valid status transitions along with the APIs that trigger them.

---

Supported Statuses

Status	Description	Reversible?
PENDING	Card has been created but not yet activated (physical cards only).	✅ Yes — via Activate Card API
ACTIVE	Card is active and can be used for transactions.	—
INACTIVE	Card is deactivated.	✅ Yes
CLOSED	Card is permanently closed.	❌ No — terminal

---

Card Creation

Card Type	Initial Status	Behavior
Virtual	ACTIVE	Auto-activated on creation
Physical	INACTIVE	Requires activation via Activate Card API

Only virtual cards are auto-activated in the PowerUp program. Physical cards are created in PENDING status and must be explicitly activated before use.

---

Status Transition Rules

1. Physical card activation: PENDING → ACTIVE via the Activate Card API (applies to physical cards at creation). This is the only valid transition out of PENDING.

2. Post-creation status updates: Once a card exists (in ACTIVE or INACTIVE status), all further transitions are handled through the Update Card Status API, which supports only three statuses: ACTIVE, INACTIVE, CLOSED.

3. ACTIVE ↔ INACTIVE: These two statuses can be toggled back and forth via the Update Card Status API.

4. CLOSED is terminal and reachable only from ACTIVE: A card must be in ACTIVE status to be closed. An INACTIVE card cannot be closed directly — it must first be moved to ACTIVE via the Update Card Status API before it can be transitioned to CLOSED. A PENDING card also cannot be closed directly — it must first be activated. Once CLOSED, no further transitions are allowed.

---

Full Transition Table

From	To	Method
(creation)	ACTIVE	Auto-activated (virtual only)
(creation)	PENDING	Default status (physical only)
PENDING	ACTIVE	Activate Card API only (initial activation)
ACTIVE	INACTIVE	Update Card Status API
INACTIVE	ACTIVE	Update Card Status API
ACTIVE	CLOSED	Update Card Status API
CLOSED	—	No further transitions (terminal)

---

Lifecycle Flowchart

     Card Created                 Card Created
     (Virtual)                      (Physical)
        │                               │
        │ auto-activated                ▼
        │                        ┌───────────┐
        │                        │  PENDING  │
        │                        └──────┬────┘
        │                               │
        │                   Activate Card API
        │                               │
        ▼                               ▼
   ┌────────────────────────────────────────┐
   │                 ACTIVE                 │◄──────────┐
   └────────┬───────────────────────────┬───┘           │
            │                           │               │
  Update Card Status API      Update Card Status API    │
        ("CLOSED")                 ("INACTIVE")         │
            │                           │               │
            ▼                           ▼      Update Card Status API
   ┌───────────────────┐         ┌────────────┐     ("ACTIVE")
   │      CLOSED       │         │  INACTIVE  │─────────┘
   │   — Terminal —    │         └────────────┘
   │ (No reactivation) │         (only "ACTIVE"
   └───────────────────┘         reachable from here)

---

Implementation / Validation Notes

1. Auto-activate virtual cards at creation; create physical cards as PENDING.
2. Require the Activate Card API to move a physical card from PENDING to ACTIVE. PENDING has no other valid transition.
3. Allow ACTIVE ↔ INACTIVE toggling via the Update Card Status API for both card types after creation.
4. CLOSED is reachable only from ACTIVE — reject any request to close a card that is currently PENDING or INACTIVE; it must be activated first.
5. Once a card is CLOSED, reject all further status update requests.
6. Log the actor/reason for every transition into CLOSED for audit and compliance purposes.