All management actions are status-driven and apply to both Debit and Prepaid cards, based on your Card Program configuration.

Choose an Action

Card Lifecycle

Every card moves through controlled states from creation to termination. These transitions ensure that cards are only usable when valid, and restricted immediately when risk is detected.

Lifecycle Phases

Note: The SHIPPED state applies only to cards with physical issuance. Digital-only cards skip this step and move directly to activation.

All Supported Statuses

Cards can perform transactions only in ACTIVE state.

Scenarios

All card management actions follow the same lifecycle: request, validate, initiate, network update, confirmation. The only difference is the action type and the resulting state transition.

sequenceDiagram
    participant User as Cardholder
    participant App as Your Application
    participant PCE as PCE
    participant Network as Card Network

    User->>App: Request card action (freeze/unfreeze/cancel/replace)
    App->>PCE: POST /card/{id}/{action}
    PCE->>PCE: Validate card state
    PCE-->>App: 200 — status *_INITIATED
    PCE->>Network: Send card status update
    Network-->>PCE: Confirmation
    PCE-->>App: Webhook — status updated
    App->>User: Confirmation message

Before you begin (all scenarios)

• Card is in a valid state for the requested action.
• Customer is ACTIVE.
• Cardholder identity has been verified.

Scenario 1: Freeze a Card Temporarily

Use this scenario when a cardholder reports a card as misplaced or you detect suspicious activity. Freezing temporarily blocks all transactions while keeping the card active for later reuse.

Business Context: A cardholder calls customer support saying they can't find their debit card. Rather than immediately canceling (which requires issuing a replacement), the support agent freezes the card for 48 hours while the customer searches. If found, it can be unfrozen instantly.

You'll also need: Card is in ACTIVE status, cardholder has verified their identity.

Request

POST /v1/customer/id/48201/issuance/card/id/55903/freeze

{
  "reason": "LOST",
  "freezeTill": "2026-07-11T23:59:59Z"
}

The card transitions ACTIVE → FREEZE_INITIATED → FREEZED. All transactions are declined while frozen.

Scenario 2: Unfreeze a Card

Use this scenario when a frozen card has been verified as safe and the cardholder wants to resume using it.

You'll also need: Card is in FREEZED status, the freeze reason has been resolved.

Request

POST /v1/customer/id/{customerId}/issuance/card/id/{cardId}/unfreeze

{
  "reason": "Card verified as safe"
}

The card transitions FREEZED → UNFREEZE_INITIATED → ACTIVE. Transactions resume immediately.

Scenario 3: Cancel a Card Permanently

Use this scenario when a card is permanently compromised, the cardholder is offboarded, or the card is no longer needed. This action is irreversible.

Business Context: A cardholder confirms their wallet was stolen. The card must be permanently cancelled to prevent any future risk.

You'll also need: Card is in ACTIVE or FREEZED status. For prepaid cards, unload remaining balance first.

Request

POST /v1/customer/id/48201/issuance/card/id/55903/cancel

{
  "reason": "STOLEN"
}

The card transitions ACTIVE → CANCELLATION_INITIATED → CANCELLED.

Scenario 4: Replace a Lost or Damaged Card

Use this scenario when a card is lost, stolen, damaged, or not delivered. The existing card is blocked and a new card is issued with new credentials.

Business Context: A cardholder's physical card was damaged. They need a replacement card shipped to their home address.

You'll also need: Card is in ACTIVE, FREEZED, or SHIPPED status. Shipping address is on file.

Request

POST /v1/customer/id/48201/issuance/card/id/55903/replace

{
  "reason": "DAMAGED",
  "shippingDetail": {
    "address": {
      "id": 1045579
    },
    "expressDelivery": "true"
  }
}

The old card is blocked, and a new card is issued with new card number, CVV, and expiry date. For digital-first cards, the cardholder can add the replacement to Apple Pay or Google Pay immediately.

Manage Card State

All actions below operate within the lifecycle defined above.

How to Think About These Actions:

• Freeze → temporary control (reversible)
• Cancel → permanent closure (irreversible)
• Replace → secure reissuance (old blocked + new issued)

All of these actions operate within the constraints defined by your Card Program and are validated against the card’s current state. Each request is checked to ensure the transition is allowed, and any attempt to perform an invalid state change will be rejected by the system.

1. Freeze or Unfreeze a Card

Temporarily pause or resume card usage without changing card details.

• Freeze a card to block all transactions → POST /v1/customer/id/{customer_id}/issuance/card/id/{card_id}/freeze
• Unfreeze a card to restore usage → POST /v1/customer/id/{customer_id}/issuance/card/id/{card_id}/unfreeze

Use following key parameters for these APIs:

Behavior

• After freeze, card transitions: ACTIVE → FREEZE_INITIATED → FREEZED
• All transactions are declined while frozen
• Unfreeze restores: FREEZED → UNFREEZE_INITIATED → ACTIVE

2. Cancel a Card

Use the POST /v1/customer/id/{customer_id}/issuance/card/id/{card_id}/cancel API to permanently deactivate a card. This action cannot be reversed.

Use when:

• Card is permanently compromised
• User is offboarded
• Card is no longer required

Behavior

• Card Transition: ACTIVE → CANCELLATION_INITIATED → CANCELLED
• Card cannot be reactivated.
• For prepaid cards, ensure balance is unloaded before cancellation.

3. Replace a Card

Use the POST /v1/customer/id/{customer_id}/issuance/card/id/{card_id}/replace API to replace an existing card with a new one for the same cardholder.

Use this action when your card is lost, stolen, or damaged.

What happens:

• Existing card is blocked.
• New card is issued with new card number, CVV and expiry date.
• New card follows standard lifecycle.