Card Status Management

Introduction

Card status is a core part of the security, risk, and operational lifecycle of every Bitnob virtual card.

Understanding how and when a card transitions between states helps your team:

Build better UX for your users,

Reduce fraud and chargebacks,

Respond intelligently to issues,

Ensure cards remain functional only when safe to do so.

Bitnob virtual cards operate under a strict three-state model:

[ACTIVE] ⇄ [FROZEN] → [TERMINATED]

Card States Explained

ACTIVE

Definition:

The card is fully operational. It can be used for all online transactions that fall within card and platform limits.

When does a card become ACTIVE?

Immediately upon successful creation via API.

After being unfrozen (if previously frozen).

What can an ACTIVE card do?

Authorize transactions,

Receive refunds,

Perform recurring/subscription payments (if supported),

Be frozen or terminated by the platform or Bitnob.

What to build:

If you're showing card state in your app, show "Active" as a green or ready status.

Always check that a card is active before initiating top-up or sending cardholder instructions.

FROZEN

Definition:

The card is temporarily suspended. It cannot perform any transactions until reactivated.

A frozen card:

Cannot authorize transactions,

Cannot be funded,

Can be reactivated (unfrozen) unless otherwise escalated.

Who can freeze a card?

You (the platform) via API,

The user (via your app or dashboard),

Bitnob’s system (automatically via fraud, refund, or risk logic).

Reasons Cards Are Frozen Automatically

reason	description
Fraud Suspicion	The system detects abnormal usage patterns, unusual merchant activity, or velocity violations.
Unauthorized Refunds	A refund arrives for a card that was never used at the original merchant.
Example:	A $20 refund from AliExpress is received on a card that never spent at AliExpress → card is frozen automatically.

Restoring a Frozen Card

To unfreeze, your app can:

Call the unfreeze endpoint,

Trigger user verification or support flow,

Monitor the card.frozen webhook and take UX action.

❗ Cards frozen for fraud may require compliance review before being reactivated.

TERMINATED

Definition:

The card is permanently deactivated. It cannot be used, funded, or reactivated.

Once terminated:

The cardholder must be issued a new card to continue transacting.

The card remains visible in transaction history for audit and dispute purposes.

Who can terminate a card?

You (via API),

Bitnob (automated),

The user (optional flow via your frontend).

Reasons Cards Are Terminated Automatically

trigger	description
Fraud Confirmation	If flagged behavior is confirmed as high-risk or abusive.
Multiple Failed Transactions	Excessive transaction declines indicate abuse or improper configuration.
Card Usage Violations	Attempts to use at disallowed MCCs, unsupported countries, or expired sessions.

Decline Thresholds That Trigger Termination

Bitnob uses intelligent thresholds to balance security with fairness:

situation	outcome
Card has at least 1 successful transaction, then gets 4 declines	Terminated
Card has never succeeded, but gets 3 declines	Terminated
Frozen card continues to receive declines matching above rules	Terminated automatically

These rules prevent automated abuse, bot testing, and retry fraud.

Status Transition Model

Developer Guide

action	api endpoint
Freeze a card	POST /cards/freeze
Unfreeze a card	POST /cards/unfreeze
Terminate a card	POST /cards/terminate
Check card status	GET /cards/:id (returns "status": "active", "frozen", or "terminated")

UX Tips for PMs & Designers

tip	why
Clearly display card status	Prevent user frustration during declined transactions
Allow users to freeze/unfreeze from your UI	Builds trust and gives control
Trigger alerts for frozen cards	Help users take quick action
Auto-hide or grey out terminated cards	Avoid confusion, but keep them visible for past spend history
Encourage creating a new card after termination	Makes recovery seamless for the user

Expert Notes

A terminated card may still receive reversals or merchant adjustments.

No new transactions will ever be allowed on a terminated card.

You should never attempt to re-use a terminated card. Always issue a fresh card.

The Trip model will show "status": "terminated" and contain final timestamps.

Webhooks

event	trigger
card.frozen	System or platform action
card.unfrozen	Re-activated by user or system
card.terminated	Final lifecycle state — irreversible

Each includes:

cardId,

userReference,

reason (if applicable),

timestamp.

The ability to control a card’s status is not just a feature — it’s a core part of your product’s security posture, trust experience and fraud response loop.

As a platform, your job is to:

React quickly to status events,

Give users visibility,

Build safeguards into your product logic,

And always respect the lifecycle transitions designed to protect the user and ecosystem.