Transaction Monitoring
Introduction
Transaction monitoring gives your team visibility into how a virtual card is being used, where it’s being declined, refunded, reversed, or topped up — and why.
This information is essential for:
End-user transparency and support,
Internal auditing and risk detection,
Compliance enforcement,
Accurate dispute and refund handling.
Bitnob records and returns a complete transaction history for every virtual card issued.
Types of Card Transactions
Each entry in a card’s transaction history represents one of the following actions:
| Type | Description |
|---|---|
| Spend | A payment for goods or services using the card. |
| Top-Up | Funds added to a card from your platform wallet. |
| Reversal | A transaction canceled after authorization, before settlement. |
| Refund | A transaction reversed by a merchant after it was already settled. |
| Chargeback | A dispute initiated by the cardholder. |
| Withdrawal | A cash withdrawal attempt (if enabled). |
| Termination | A system or user-initiated card shutdown, may include balance refund. |
Each transaction is stored and exposed via API, with relevant metadata like amount, timestamp, merchant name, MCC, and outcome.
How to Retrieve Transactions
Optional Filters
status — approved, declined, reversed, refunded
type — spend, topup, refund, etc.
dateFrom, dateTo — ISO timestamp range
Sample Response
Declined Transactions
When a transaction fails, Bitnob records the reason and exposes it via both API and webhooks.
Common Decline Reasons
| Code | Explanation |
|---|---|
| insufficient_funds | Card doesn’t have enough balance. |
| card_inactive | Card is frozen or terminated. |
| mcc_not_allowed | The merchant’s category is restricted (e.g., crypto, gambling, dating). |
| invalid_card_details | Incorrect CVV, PAN, or expiry entered. |
| international_blocked | Card restricted from cross-border transactions. |
| velocity_limit | Too many transactions in short time. |
| issuer_downtime | Technical issues with card processor. |
| fraud_block | Auto-flagged for suspicious behavior. |
UX Tip: Always display the decline reason clearly. It builds user trust and reduces support tickets.
Merchant Restrictions (MCC Blocklist)
Some merchant categories are blocked by default for regulatory, fraud, or policy reasons.
| MCC | Description |
|---|---|
| 4829 | Money transfer |
| 6051 | Non-fiat currency services (e.g., crypto exchanges) |
| 7995 | Betting and gambling |
| 7273 | Dating services |
| 5966 | Telemarketing merchants |
| 7801–7802 | Licensed online casinos and racing (US region) |
These codes are enforced at the processor level. Even if a merchant appears online, transactions to these MCCs will be declined by design.
Refunds and Reversals
| Type | Description |
|---|---|
| Reversal | Authorization was approved, but merchant canceled before settlement. Funds are released. |
| Refund | Transaction was settled, then merchant issued a refund. Amount is returned to card balance or platform wallet. |
Notes:
Reversals take 3–14 business days depending on the merchant.
If the card is terminated, reversals are still accepted and credited to the master balance.
Refunds on inactive cards are redirected to the platform wallet, not to the card itself.
Chargebacks
A chargeback occurs when a cardholder disputes a transaction due to fraud or merchant failure.
| Characteristic | Detail |
|---|---|
| Initiator | Cardholder (via your platform) |
| Process | Investigation, evidence collection, formal Visa dispute |
| Outcome | Reversal of funds if dispute is successful |
| Timeline | May take up to 60 days |
| Fees | Chargebacks may incur processor or network fees |
Refunds are merchant-initiated, chargebacks are user-initiated.
Top-Up Transactions
These represent manual or programmatic funding of a card.
| Rule | Note |
|---|---|
| Source | Bitnob wallet (BTC, USDT, NGN, etc.) |
| Status | Always approved if funding succeeds |
| Active cards only | You can’t fund frozen or terminated cards |
Termination Transactions
When a card is terminated, Bitnob logs the event as a transaction. If a balance exists:
It may be refunded to the platform’s float account,
A $1 system termination fee is applied where relevant.
Even after termination, the card may still receive:
Reversals
Refunds
Authorization attempts (which will be auto-declined)
Withdrawal Transactions
Withdrawals reduce card balance via ATM or POS, if enabled. By default, Bitnob cards do not support POS or ATM use.
| Rule | Description |
|---|---|
| Min balance required | $1 must remain after withdrawal |
| Card must be active | Withdrawals only work for live cards |
| Subject to limits | Daily withdrawal caps apply |
UX and Product Recommendations
| Feature | Why It Matters |
|---|---|
| Show transaction list clearly | Builds transparency and trust |
| Label declined and refunded clearly | Prevents user confusion |
| Show decline reason text | Reduces unnecessary support calls |
| Group by day/week/month | Makes reports readable |
| Include merchant name and MCC | Aids recognition and auditing |
| Allow CSV export (optional) | Helps small businesses and teams using the card |
Webhooks
| Event | Description |
|---|---|
| transaction.success | A charge was successfully authorized |
| transaction.decline | A charge was attempted and rejected |
| transaction.refund | Merchant refunded user |
| transaction.reversal | Merchant canceled pending transaction |
| transaction.chargeback.initiated | Dispute submitted |
| transaction.chargeback.resolved | Final chargeback decision posted |
Webhooks are essential for triggering alerts, spend analytics, or custom reconciliation workflows.
Transaction monitoring is your first line of defense for:
Risk detection,
Support ticket resolution,
Spend transparency,
Operational control.
Design your apps and dashboards to reflect these events clearly — and your cardholders will trust the product even when things go wrong.
