💰 User Wallet & Transaction Ledger

📋 Description

User Wallet & Transaction Ledger is a comprehensive wallet and transaction management system for WordPress. This plugin provides a robust financial infrastructure that enables you to manage user balances, process transactions, and maintain a complete audit trail of all wallet activities. Built with atomic operations and idempotency guarantees, it ensures data integrity and consistency for all financial transactions.

The plugin is designed for WordPress sites that need to track user credits, process charges, issue refunds, and maintain detailed transaction histories. Whether you’re building a marketplace, membership site, content platform, or any application requiring user balance management, this plugin provides the foundation you need.

✨ Features

• 💱 Multi-Currency Wallet System: Create and manage wallets for users in multiple currencies (USD, EUR, GBP, JPY, and more)
• ⚛️ Atomic Balance Operations: All balance changes are processed atomically with database-level consistency guarantees
• 📊 Complete Transaction Ledger: Immutable audit trail of all wallet activities including credits, debits, refunds, and adjustments
• 🔒 Idempotency Protection: Built-in idempotency keys prevent duplicate transactions from accidental retries
• 🌐 RESTful API: Comprehensive REST API endpoints for programmatic wallet management
• 🎛️ Admin Management Interface:
  • Wallet Management screen for viewing and managing user wallets
  • Transaction Log screen with filtering and search capabilities
  • User profile integration showing wallet balances and transaction history
  • Manual credit/debit operations with reason tracking
• 👨‍💻 Developer-Friendly PHP API: Simple function-based API for integrating wallet operations into your code
  • wallet_get_balance() – Retrieve user balance
  • wallet_can_charge() – Check if user can afford a charge
  • wallet_charge_user() – Debit from user wallet
  • wallet_credit_user() – Add credits to user wallet
  • wallet_refund_transaction() – Refund a previous transaction
• 🔍 Transaction Sources: Track transaction origins (API, Admin, WooCommerce, System)
• 🏷️ Metadata Support: Attach custom metadata to any transaction for extended tracking
• 🪝 WordPress Hooks: Action hooks for wallet and transaction events
• 🛡️ Security: Role-based capability system with granular permissions
• ⚙️ Configurable Settings: Customize default currency and other wallet behaviors

📥 Installation

Click the ‘Download Plugin’ button to download the zip file. Upload that file to your WordPress site.

📖 Usage

👤 For Administrators

After installation, you’ll find a new “Wallet Management” menu item in your WordPress admin dashboard.

💼 Managing User Wallets:

1. Navigate to Wallet Management > Manage Wallets
2. View all user wallets with current balances
3. Use the search function to find specific users
4. Credit or debit user accounts manually with required reason/description
5. View wallet details and transaction history for any user

📝 Viewing Transactions:

1. Navigate to Wallet Management > Transaction Log
2. Filter transactions by type, source, date range, or user
3. Export transaction data for accounting purposes
4. View complete transaction details including metadata

⚙️ Configuring Settings:

1. Navigate to Wallet Management > Settings
2. Set the default currency for new wallets
3. Configure transaction behavior and restrictions

👥 User Profile Integration:

When viewing or editing any user profile, you’ll see a “Wallet Information” section displaying:

• Current balance for each currency
• Recent transaction history
• Quick actions for manual adjustments

👨‍💻 For Developers

🔧 Basic PHP Usage:

// Get user's balance
$result = \aiplugin4686\wallet_get_balance( $user_id, 'USD' );
if ( $result['success'] ) {
    echo 'Balance: ' . $result['formatted_balance'];
}

// Check if user can afford a purchase
$can_afford = \aiplugin4686\wallet_can_charge( $user_id, 1000, 'USD' ); // 1000 = $10.00

// Charge user's wallet
$charge_result = \aiplugin4686\wallet_charge_user(
    $user_id,
    1000, // Amount in minor units (cents)
    array(
        'description' => 'Purchase of premium content',
        'source' => 'woocommerce',
        'metadata' => array(
            'order_id' => 12345,
            'product_id' => 67890
        )
    )
);

// Credit user's wallet
$credit_result = \aiplugin4686\wallet_credit_user(
    $user_id,
    5000, // $50.00
    array(
        'description' => 'Promotional bonus',
        'source' => 'admin'
    )
);

// Refund a transaction
$refund_result = \aiplugin4686\wallet_refund_transaction(
    $transaction_id,
    array(
        'description' => 'Order cancelled by customer'
    )
);

💵 Note on Amount Values: All monetary amounts are specified in “minor units” (cents for USD, pence for GBP, etc.). For example:

• $10.00 = 1000 minor units
• $0.50 = 50 minor units
• €25.99 = 2599 minor units

🌐 Using the REST API:

The plugin provides REST endpoints under the metered-wallet/v1 namespace:

• GET /wp-json/metered-wallet/v1/me/balance – Get current user’s balance
• GET /wp-json/metered-wallet/v1/me/transactions – Get current user’s transaction history
• POST /wp-json/metered-wallet/v1/charge – Charge a user (requires admin capability)
• POST /wp-json/metered-wallet/v1/credit – Credit a user (requires admin capability)

🪝 WordPress Hooks:

// When a wallet is created
add_action( 'wp_metered_wallet_created', function( $wallet_id, $user_id, $currency ) {
    // Your code here
}, 10, 3 );

// When a user is charged
add_action( 'wp_metered_wallet_user_charged', function( $transaction_id, $user_id, $amount, $currency ) {
    // Your code here
}, 10, 4 );

// When a user is credited
add_action( 'wp_metered_wallet_user_credited', function( $transaction_id, $user_id, $amount, $currency ) {
    // Your code here
}, 10, 4 );

// When a transaction is refunded
add_action( 'wp_metered_wallet_transaction_refunded', function( $refund_transaction_id, $original_transaction_id ) {
    // Your code here
}, 10, 2 );

🔐 Security & Permissions

The plugin implements a comprehensive capability system:

• manage_wallets – Full wallet management access (typically administrators)
• view_wallets – View wallet information (shop managers, etc.)
• process_transactions – Process credits and debits

💡 Use Cases

• 🛒 E-commerce Sites: Store credit, gift cards, loyalty points
• 📰 Content Platforms: Pay-per-view content, subscription credits
• 🎓 Learning Management: Course credits, tutoring hours
• 🏪 Marketplaces: Vendor balances, escrow systems
• 🎮 Gaming Platforms: In-game currency, virtual goods
• 💼 Service Platforms: Prepaid service hours, consultation credits

🆘 Support

For questions, issues, or feature requests, please contact the site administrator.