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 new transactions,

Cannot be funded,

Can still receive settlements for transactions that were already authorized before the freeze,

Can be reactivated (unfrozen) unless otherwise escalated.

Who can freeze a card?

You (the platform) via Update Card Status,

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 virtualcard.transaction.declined.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.
Repeated Unsettled Authorizations	Cards are permanently terminated on the 3rd decline rule violation, after the decline fee is charged.

Decline Thresholds That Trigger Termination

For full details on decline thresholds, fee schedules, and how to avoid violations, see the Decline Rule Policy.

Status Transition Model

Developer Guide

Reference for each call: Update Card Status for freeze/unfreeze, Terminate Card, and Get Card to read the current status.

action	api endpoint
Freeze a card	POST /api/cards/:cardId/status with { "status": "frozen" }
Unfreeze a card	POST /api/cards/:cardId/status with { "status": "active" }
Terminate a card	DELETE /api/cards/:cardId (irreversible; cannot be called within 24h of creation)
Check card status	GET /api/cards/:cardId (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

Payloads for these events are documented under Virtual Card Declines and Virtual Cards Created.

event	trigger
virtualcard.transaction.declined.frozen	Card was frozen due to flagged activity (fraud rule)
virtualcard.transaction.declined.terminated	Card was auto-terminated due to multiple failed attempts

Each includes:

cardId,

reference,

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.