editor_options: markdown: wrap: 72 —

Virtual Card Data Management System - US Edition

🇺🇸 Enhanced version specifically designed for US users with automatic bank balance updates

A secure desktop application for managing physical card information, generating virtual card numbers, and automatically updating balances from US bank accounts.

🚀 US Edition Features

🏦 Automatic Bank Integration

  • Plaid Integration: Connect to 11,000+ US banks and credit unions
  • Direct Bank APIs: Support for major US banks (Chase, Bank of America, Wells Fargo, etc.)
  • Real-time Balance Updates: Automatic balance synchronization every 5 minutes
  • Transaction Monitoring: Automatic transaction import and categorization

💳 Enhanced Card Management

  • US Bank Support: Optimized for major US financial institutions
  • Credit Card Features: Credit limit tracking, available credit calculation
  • Account Types: Support for checking, savings, credit cards, and debit cards
  • Multi-Bank Management: Manage cards from different banks in one place

🔄 Automatic Updates

  • Smart Scheduling: Configurable update intervals (1-60 minutes)
  • Error Handling: Automatic retry with exponential backoff
  • Connection Management: Monitor and manage bank connections
  • Manual Override: Force immediate balance updates when needed

📊 US-Specific Analytics

  • Spending Categories: Automatic transaction categorization
  • Credit Utilization: Track credit usage across all cards
  • Balance History: Historical balance tracking and trends
  • Bank Comparison: Compare balances and activity across institutions

🛠️ Installation & Setup

Prerequisites

  • Python 3.8 or higher
  • Internet connection (for bank integration)
  • US bank account credentials or Plaid developer account

Quick Start

  1. Download and Install:

    python install.py

  2. Start US Edition:

    # Windows
start_us.bat

# Linux/Mac
./start_us.sh

  3. First-Time Setup:

    • Set your master password
    • Add your first US card
    • Connect to your bank account

🏦 Bank Connection Setup

Option 2: Direct Bank APIs

For major banks with direct API access.

Supported Banks: - Chase Bank - Bank of America - Wells Fargo - Citibank - Capital One - American Express - Discover

Setup Process: 1. Contact your bank for API credentials 2. Add credentials in the Bank Manager 3. Test connection and enable auto-updates

⚙️ Configuration

US-Specific Settings

Edit config/settings_us.json:

{
  "us_banking": {
    "balance_update_interval": 300,
    "plaid_config": {
      "client_id": "your_plaid_client_id",
      "secret": "your_plaid_secret",
      "environment": "sandbox"
    }
  },
  "monitoring": {
    "low_balance_threshold": 100.0,
    "high_spending_threshold": 1000.0
  }
}

Update Intervals

  • Minimum: 1 minute (for testing)
  • Recommended: 5 minutes (default)
  • Maximum: 60 minutes
  • Off-hours: Reduced frequency (11 PM - 6 AM)

🔒 Security & Privacy

Bank-Grade Security

  • OAuth 2.0: Secure authentication with banks
  • No Credential Storage: Plaid handles bank credentials securely
  • Encrypted Tokens: All access tokens encrypted locally
  • Read-Only Access: Cannot initiate transactions or transfers

Data Protection

  • Local Storage: All data stored locally on your device
  • End-to-End Encryption: Sensitive data encrypted with your master password
  • No Cloud Sync: Data never leaves your device
  • Audit Logging: Complete activity logs for security monitoring

📱 User Interface

Main Dashboard

  • Card Overview: All cards with real-time balances
  • Bank Status: Connection status for each bank
  • Auto-Update Toggle: Enable/disable automatic updates
  • Quick Actions: Manual refresh, bank manager, transactions

Bank Manager

  • Connection Status: Monitor all bank connections
  • Error Handling: View and resolve connection issues
  • Manual Updates: Force immediate balance refresh
  • Connection History: Track update frequency and success rates

Enhanced Card Details

  • Financial Summary: Balance, credit limit, available credit
  • Bank Information: Institution name, account type, last update
  • Transaction History: Recent transactions with categories
  • Update Schedule: Next scheduled update time

🔧 Troubleshooting

Common Issues

1. Bank Connection Failed - Verify internet connection - Check bank credentials - Ensure bank supports API access - Try reconnecting through Plaid

2. Balance Not Updating - Check auto-update status - Verify bank connection is active - Review error logs in Bank Manager - Try manual update

3. Plaid Connection Issues - Verify Plaid credentials in settings - Check Plaid service status - Ensure account is in good standing - Re-authenticate if needed

4. High Error Rate - Check rate limiting settings - Verify bank API quotas - Review connection stability - Consider increasing update interval

Log Files

  • Application: logs/app_us.log
  • Bank Integration: logs/bank_integration.log
  • Audit Trail: logs/audit_us.log

🆕 US Edition Enhancements

New Features vs Standard Version

Feature Standard US Edition
Manual Balance Entry ✅ ✅
Auto Bank Updates ❌ ✅
Plaid Integration ❌ ✅
Credit Limit Tracking ❌ ✅
Transaction Import ❌ ✅
Multi-Bank Support ❌ ✅
Spending Analytics ❌ ✅
Real-time Notifications ✅ ✅ Enhanced

Performance Optimizations

  • Efficient API Calls: Batch requests and intelligent caching
  • Background Updates: Non-blocking balance updates
  • Smart Scheduling: Avoid peak banking hours
  • Error Recovery: Automatic retry with backoff

🔄 Update Schedule

Automatic Updates

  • Business Hours: Every 5 minutes (9 AM - 6 PM)
  • Evening: Every 15 minutes (6 PM - 11 PM)
  • Night: Every 30 minutes (11 PM - 6 AM)
  • Weekends: Every 10 minutes

Manual Updates

  • Instant: Click “Manual Update” for immediate refresh
  • Bulk Update: Update all connected accounts at once
  • Selective: Update specific cards only

📊 Analytics & Reporting

Transaction Analysis

  • Category Breakdown: Spending by category
  • Merchant Analysis: Top merchants and frequency
  • Monthly Summaries: Detailed monthly reports
  • Export Options: CSV, PDF export for external analysis

🌟 Pro Tips

Maximizing Auto-Updates

  1. Stable Internet: Ensure reliable internet connection
  2. Bank Maintenance: Be aware of bank maintenance windows
  3. Rate Limits: Don’t exceed bank API limits
  4. Error Monitoring: Regularly check Bank Manager for issues

Security Best Practices

  1. Strong Master Password: Use complex, unique password
  2. Regular Backups: Enable automatic backups
  3. Monitor Logs: Review audit logs regularly
  4. Update Software: Keep application updated

Optimization Tips

  1. Update Frequency: Balance freshness vs. API usage
  2. Connection Management: Remove unused connections
  3. Error Handling: Address connection errors promptly
  4. Performance: Close unused applications during updates

📞 Support & Resources

Getting Help

  • Documentation: Complete user manual included
  • Log Analysis: Check application logs for errors
  • Bank Support: Contact your bank for API issues
  • Plaid Support: Use Plaid dashboard for connection issues

📄 License & Compliance

Regulatory Compliance

  • PCI DSS: Payment card industry compliance
  • SOX: Sarbanes-Oxley compliance for financial data
  • GLBA: Gramm-Leach-Bliley Act compliance
  • State Regulations: Compliant with US state financial regulations

Data Handling

  • No Data Sharing: Data never shared with third parties
  • Local Processing: All processing done locally
  • Secure Deletion: Secure data deletion when removing cards
  • Audit Trail: Complete audit trail for compliance

Version: 1.0.0 US Edition
Last Updated: February 8, 2026
Developer: Societas AI
License: MIT License

🇺🇸 Built specifically for US users with US banking integration