Skip to main content

​
Learning objectives

  • Understand the lifecycle states of a virtual card
  • Learn what causes transitions between active, frozen, and terminated states
  • Know how to implement these operations through your backend and API
  • Design a clear user experience around lifecycle events
  • Handle edge cases and system-triggered freezes or terminations confidently

​
Card lifecycle: a quick review

Cards may transition between these states due to:
  • User actions (e.g., tapping “freeze” in your UI)
  • Risk systems detecting anomalies
  • Automatic rules defined by the processor or issuing bank

​
Freezing a card

What Freezing Means Freezing a virtual card disables all spend activity temporarily, but preserves the card and its balance. It is typically used:
  • To protect against fraud or unauthorized activity
  • As a user-triggered pause during suspicious activity
  • To prevent further failed transactions
  • While conducting internal reviews or KYC validation
Frozen cards:
  • Cannot be used for payments
  • Cannot be topped up
  • Remain visible in the user’s dashboard
  • Can be unfrozen (if permitted by platform or rules)
Both freeze and unfreeze go through Update Card Status.

​
Unfreezing a card

Unfreezing restores a card to its active state, allowing it to be used again. Unfreezing should be:
  • Controlled by user action (with optional PIN or biometric confirmation)
  • Logged internally with timestamp and initiator
  • Denied if the card is already in a terminated state
Only active or frozen cards can transition. Terminated cards are final.

​
Terminating a card

What Termination Means Termination is a permanent deactivation. Once a card is terminated, it:
  • Cannot be used for any further transactions
  • Cannot be unfrozen
  • Will not accept new top-ups
  • May still receive pending refunds or reversals
Termination is typically triggered by: Automatic Termination Rules (Example) Your backend should track decline history and enforce these limits, or respond to Bitnob webhooks accordingly. Refunds on Terminated Cards If a terminated card receives a refund:
  • The funds are credited to your platform’s float or master wallet
  • Users must be notified via your support or automated system
  • A webhook (virtualcard.transaction.terminated.refund) fires for the balance refund, with the amount and card details
Cards may still receive reversals or refunds even after termination, depending on merchant behavior. A merchant refund arrives as virtualcard.transaction.refund, so handle both events. Withdrawal Behavior Before and After Lifecycle Changes
  • Frozen cards cannot be used for withdrawal
  • A withdrawal must leave at least $1 on the card
  • Termination refunds any remaining balance to your wallet

​
Webhooks to monitor

Always notify your support team or alerting system when these webhooks are received.

​
UI and product design guidelines

Never hide cards or delete terminated cards from the user’s view. Always display a history for trust and support.

​
Developer considerations

  • Log all lifecycle transitions (who triggered them and when)
  • Deny any transactions or API calls for terminated cards
  • Ensure top-up logic validates the current card status
  • Build idempotency and timestamp-based reconciliation to handle race conditions
  • If cards are terminated in a batch or via automated logic, enqueue for notification and refund processing

​
Recap

  • Cards exist in one of three states: Active, Frozen, or Terminated
  • Freezing is temporary and reversible; termination is permanent
  • Platform rules and card processors define when cards are auto-terminated
  • Refunds after termination are redirected to your platform wallet
  • User-facing and admin-facing tools should always reflect the true state