Card Lifecycle Model

Cards issued within the platform follow a structured operational lifecycle.

Each card is issued under the hierarchy: Client → Product → Cardholder

The lifecycle defines how a card moves from issuance through active use to eventual termination. The card’s current state controls all operational capabilities, including transaction eligibility and configuration updates.

State Management Principles

The platform enforces the following core principles:

• A card always has exactly one authoritative state.

• State transitions must be explicitly requested via authorized API operations.

• Unauthorized or invalid transitions are rejected.

• Certain transitions are irreversible (e.g. Lost, Stolen, or Destroyed cards).

• State changes take effect immediately and are reflected in all subsequent API responses and transaction decisions.

These rules guarantee consistent lifecycle behavior across every Client.

Card States

Cards transition through three primary operational states:

1. Active — Card is fully operational and ready for use.

   Transaction Eligibility: Allowed

   Reversible: Yes

2. Suspended — Card is restricted (temporary or permanent).

   Transaction Eligibility: Declined

   Reversible: Depends on reason

3. Deactivated — Card is permanently terminated.

   Transaction Eligibility: Declined

   Reversible: No

State transitions are performed exclusively through authorized API calls. Once a card is Deactivated, it cannot be returned to any other state.

Lifecycle Operations

The platform supports the following lifecycle actions:

• Card activation

• Temporary suspension and unsuspension

• Irreversible suspension (e.g. Lost, Stolen, Fraud)

• Permanent deactivation

• Reissuance (new physical or virtual card for the same cardholder)

• Configuration updates (when permitted by current state)

All lifecycle actions:

• Are validated within the requesting Client’s scope

• Require appropriate role authorization

• Return the updated card object with the new state upon completion

Lifecycle and Transaction Behavior

The card state directly determines transaction outcomes:

• Active cards are eligible for authorization.

• Suspended or Deactivated cards are automatically declined.

• Product-level security policies and velocity controls continue to apply on top of the card state.

Transaction responses always reflect the card’s current operational state at the time of processing.

Advanced Integration

For complete API reference, request/response examples, state synchronization patterns, webhook events, error handling, and underlying details, refer to: → Thredd Cards API Guide (Advanced Integration)