Module 6: Spend Transactions and Monitoring
🧠 Learning Objectives
By the end of this module, you should be able to:
Understand how virtual card spend transactions work, including authorizations and settlements
Identify the data returned from successful and failed transactions
Monitor and store transaction history for user transparency and operational integrity
Integrate webhook-based monitoring for real-time updates
Handle common transaction scenarios like reversals, refunds, and declines
What Is a Spend Transaction?
A spend transaction occurs when a virtual card is used to pay for goods or services. This includes:
Online purchases (e.g., Amazon, Jumia, Shopify)
Subscriptions (e.g., Netflix, Spotify, Notion)
In-app billing
Software tools and services
Every transaction attempt results in either an authorization success or failure. Your system must listen to these outcomes and update the user interface and internal records accordingly.
The Authorization Flow
Every virtual card spend follows this basic authorization flow:
User enters card details at checkout
Merchant submits an authorization request
Card processor checks:
Card status (active, frozen, terminated)
Available balance
Merchant category code (MCC) restrictions
Velocity and fraud rules
Authorization is approved or declined
Bitnob (or your card provider) sends a webhook with the result
Your system stores and displays the result
Successful Transactions
When a spend transaction is successful:
The authorized amount is deducted from the card balance
The transaction is recorded in your system
A webhook is fired (e.g., virtualcard.transaction.debit )
The card remains in its current lifecycle state unless further action is taken
Declined Transactions
A transaction may be declined for a number of reasons. These events will still generate a webhook and must be handled gracefully in the UI.
Common decline reasons include:
Insufficient funds
Card is frozen or terminated
Merchant falls under a restricted MCC
Too many recent transactions (velocity limit)
Processor-level technical errors
You should always show a clear explanation in your product: “Your card was declined because the balance was too low.”
Reversals, Refunds, and Authorizations
Not all spend-related events result in a completed payment. Your system must track the following:
| Type | Description |
|---|---|
| Authorization Reversal | Transaction was approved but canceled before settlement |
| Refund | Payment was settled but later refunded by the merchant |
| Authorization Failure | Request was rejected before authorization (e.g., bad CVV, unsupported merchant) |
Each has a different webhook and handling logic. These scenarios are especially common in subscription trials, hotel bookings, and digital advertising.
Transaction Webhooks to Integrate
| Event | Trigger |
|---|---|
| virtualcard.transaction.debit | Approved payment |
| virtualcard.transaction.declined | Failed payment |
| virtualcard.transaction.refund | Refund received from merchant |
| virtualcard.transaction.reversed | Authorization reversed before settlement |
| virtualcard.transaction.authorization.failed | Authorization rejected by card processor |
| virtualcard.transaction.crossborder | Cross-border charge detected |
| virtualcard.transaction.terminated.refund | Refund processed for terminated card |
These events allow you to update balances, send alerts, generate logs, and monitor fraud patterns.
What to Track in Your Database
Each transaction should be stored with the following fields:
Transaction ID
Card ID
User reference (if applicable)
Amount
Currency
Timestamp
Status (approved, declined, refunded, reversed )
Merchant name and MCC (if available)
Failure reason (if applicable)
Your database should allow filtering by user, card, status, and time range.
User Interface Recommendations
Your product should provide:
A transaction list showing:
Merchant name or narrative
Amount and currency
Date and time
Status (success, declined, reversed, refunded)
A detailed transaction view for support and transparency:
MCC Fees
Status change timeline
Original authorization reference
A clear and human-readable explanation of failures:
“This payment was declined because your balance was too low”
“This merchant is not supported by your card provider”
Decline Thresholds and Automated Termination
Bitnob (or the card processor) may automatically terminate a card if it fails repeatedly:
If a card has one or more successful transactions, it may be terminated after four consecutive declines
If a card has never had a successful transaction, it may be terminated after three declines
Cards may also be frozen or terminated based on transaction velocity or fraud rules
Track decline counts and terminate cards in sync with your provider's logic.
Internal Monitoring Recommendations
For product, ops, and support teams:
Create alerts for cards with multiple declines in short timeframes
Flag suspicious MCCs (e.g., gambling, money transfer)
Monitor refunds and reversals against total spend
Log all webhook receipts and response statuses
Recap
Every card spend triggers a success or failure event
You must listen to webhooks, log transactions, and update your user interface
Successful transactions deduct balance; failed ones do not
Track declines carefully, as they may result in card termination
Transparency builds trust: always tell users what happened and why
