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.
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.
