Every card follows a lifecycle from creation to cancellation. You manage transitions through the Update Card Status endpoint.
Status reference
Status flow
Freeze a card
Freezing temporarily disables all transactions. All incoming authorizations are declined until the card is unfrozen.
Response:
A card.status.update.succeeded webhook fires once the freeze is applied:
Unfreeze a card
To reactivate a frozen card, set the status back to ACTIVE:
Cancel a card
Cancellation is irreversible. A cancelled card cannot be reactivated.
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
To avoid the 30-day wait, withdraw the remaining balance before cancelling the card using the Card Withdraw endpoint. Webhook sequence
card.status.update.succeeded with card_status: PRE_CANCEL — immediately after the cancel requestcard.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 and Activation Status webhooks respectively.
