Module 6: Spend transactions and monitoring

​

Learning objectives

• 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?

• Online purchases (e.g., Amazon, Jumia, Shopify)
• Subscriptions (e.g., Netflix, Spotify, Notion)
• In-app billing
• Software tools and services

​

The authorization flow

1. User enters card details at checkout
2. Merchant submits an authorization request
3. Card processor checks:

• Card status (active, frozen, terminated)
• Available balance
• Merchant category code (MCC) restrictions
• Velocity and fraud rules

1. Authorization is approved or declined
2. Bitnob (or your card provider) sends a webhook with the result
3. Your system stores and displays the result

​

Successful transactions

• The authorized amount is deducted from the card balance
• The transaction is recorded in your system
• A webhook is fired (e.g., virtualcard.transaction.settlement)
• The card remains in its current lifecycle state unless further action is taken

{
  "event_id": "06cd8fab-da0b-4c4d-87e8-0a1b2c3d4e5f",
  "event": "virtualcard.transaction.settlement",
  "data": {
    "cardId": "abc123",
    "id": "tx_debit_a1b2c3d4e5f6",
    "companyId": "<company_uuid>",
    "amount": 49990000,
    "display_amount": 49.99,
    "currency": "USD",
    "transaction_type": "settlement",
    "reference": "spend_txn_001",
    "narrative": "Settlement at spotify",
    "timestamp": "2026-05-16T14:22:10Z",
    "status": "completed",
    "reason": null,
    "merchant_name": "spotify",
    "merchant_mcc": "5815",
    "merchant_country": "SWE"
  }
}

​

Declined transactions

• Insufficient funds
• Card is frozen or terminated
• Merchant falls under a restricted MCC
• Too many recent transactions (velocity limit)
• Processor-level technical errors

{
  "event_id": "a0678495-74a5-46e7-9283-a45b6c7d8e9f",
  "event": "virtualcard.transaction.declined",
  "data": {
    "cardId": "abc123",
    "id": "tx_decline_d4e5f7a1b2c3",
    "companyId": "<company_uuid>",
    "amount": 200000000,
    "display_amount": 200.0,
    "currency": "USD",
    "transaction_type": "authorization_declined",
    "reference": "decline_ref_0123d456",
    "narrative": "Authorization declined at google_ads",
    "timestamp": "2026-05-16T12:30:45Z",
    "status": "decline",
    "reason": "Insufficient funds",
    "merchant_name": "google_ads",
    "merchant_mcc": "7311",
    "merchant_country": "USA"
  }
}

​

Reversals, refunds, and authorizations

​

Transaction webhooks to integrate

​

What to track in your database

• 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)

​

User interface recommendations

1. A transaction list showing:

• Merchant name or narrative
• Amount and currency
• Date and time
• Status (success, declined, reversed, refunded)

2. A detailed transaction view for support and transparency:

• MCC Fees
• Status change timeline
• Original authorization reference

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

• A card is terminated after repeated decline violations. The default is 3, and each company’s limit can be set from 1 to 10
• From the second violation, a $0.75 decline fee applies
• An approved authorization resets the count to zero
• Cards may also be frozen or terminated based on transaction velocity or fraud rules

​

Internal monitoring recommendations

• 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