PHPackages zfhassaan/laravel-wallet - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Payment Processing](/categories/payments) 4. / 5. zfhassaan/laravel-wallet ActiveLibrary[Payment Processing](/categories/payments) zfhassaan/laravel-wallet ======================== Ledger-based e-wallet system for Laravel with secure wallet creation, atomic transfers, immutable transactions, and audit-friendly balance calculation. Built for fintech, SaaS platforms, and marketplaces requiring safe, extensible digital wallet infrastructure. 00PHPCI passing Since Jan 27Pushed 3mo agoCompare [ Source](https://github.com/zfhassaan/laravel-wallet)[ Packagist](https://packagist.org/packages/zfhassaan/laravel-wallet)[ RSS](/packages/zfhassaan-laravel-wallet/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependenciesVersions (1)Used By (0) Laravel Wallet ============== [](#laravel-wallet) A powerful, ledger-based e-wallet system for Laravel applications. Built with security, auditability, and extensibility in mind. [![Latest Version](https://camo.githubusercontent.com/a6e7f2bad1f691772f6d3f59db4098d3d299d1ad592a112f772386dc2e0dc4aa/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7a666861737361616e2f6c61726176656c2d77616c6c65742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/zfhassaan/laravel-wallet)[![Total Downloads](https://camo.githubusercontent.com/6e36b31b4d38869444a4408d7ad50dfd7039164292e98e1141a759024d4ccebc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7a666861737361616e2f6c61726176656c2d77616c6c65742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/zfhassaan/laravel-wallet)[![License](https://camo.githubusercontent.com/68acad143efacf69149edbb40de3a6ba2c617d981a65b416a1a8eaaba8bae901/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f7a666861737361616e2f6c61726176656c2d77616c6c65742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/zfhassaan/laravel-wallet) Features -------- [](#features) - **Ledger-Based Architecture**: Balance is calculated from immutable transaction records, not stored in a mutable column - **Tamper Detection**: Automatic wallet integrity verification with balance hash validation - **Atomic Transfers**: Guaranteed consistency with database transactions and row-level locking - **Security First**: Password protection, rate limiting, wallet freezing, and comprehensive validation - **Audit Trail**: Complete transaction history with UUIDs, references, and metadata - **QR Payments**: Generate and process secure QR code payments for instant wallet-to-wallet transactions - **Conversion Rates**: Flexible conversion rate system (1:1, 10:1, 100:1, etc.) for different currency representations - **Production Ready**: Database transactions, row locking, minor units handling, and comprehensive error handling Requirements ------------ [](#requirements) - PHP 8.2+ - Laravel 12+ Installation ------------ [](#installation) Install the package via Composer: ``` composer require zfhassaan/laravel-wallet ``` Publish the configuration file (optional): ``` php artisan vendor:publish --tag=laravel-wallet-config ``` Run the migrations: ``` php artisan migrate ``` Quick Start ----------- [](#quick-start) ### 1. Add the Trait to Your User Model [](#1-add-the-trait-to-your-user-model) ``` use Zfhassaan\LaravelWallet\Traits\HasWallets; class User extends Authenticatable { use HasWallets; } ``` ### 2. Create a Wallet [](#2-create-a-wallet) ``` use LaravelWallet; $wallet = LaravelWallet::createWallet($user); ``` ### 3. Credit the Wallet [](#3-credit-the-wallet) ``` // Amount in minor units (paisa for PKR, cents for USD) // 1000 = 10.00 PKR (assuming 100:1 conversion rate) LaravelWallet::credit($wallet, 1000); ``` ### 4. Get Balance [](#4-get-balance) ``` $balance = LaravelWallet::balance($wallet); // Returns balance in minor units ``` ### 5. Transfer Funds [](#5-transfer-funds) ``` $result = LaravelWallet::transfer($fromWallet, $toWallet, 500); // Returns array with 'debit' and 'credit' transactions ``` Core Concepts ------------- [](#core-concepts) ### Ledger-Based System [](#ledger-based-system) Unlike traditional wallet systems that store balance in a mutable column, Laravel Wallet calculates balance from transaction records: ``` Balance = SUM(credits) - SUM(debits) ``` This approach provides: - **Audit Safety**: Every transaction is immutable and traceable - **Race Condition Prevention**: Row-level locking ensures consistency - **Tamper Detection**: Balance hash validation detects any unauthorized changes ### Minor Units [](#minor-units) All amounts are stored in **minor units** (e.g., paisa for PKR, cents for USD). This eliminates floating-point precision issues and ensures accurate financial calculations. ``` // 10.00 PKR = 1000 paisa (with 100:1 conversion rate) LaravelWallet::credit($wallet, 1000); ``` ### Conversion Rates [](#conversion-rates) Control how wallet values are represented with flexible conversion rates: ``` // Set conversion rate (100 = 100 paisa = 1 PKR) LaravelWallet::setConversionRate($wallet, 100); // Or create wallet with custom rate $wallet = LaravelWallet::createWallet($user, 'PKR', [ 'conversion_rate' => 10 // 10:1 ratio ]); // Convert between major and minor units $majorUnits = LaravelWallet::toMajorUnits($wallet, 1000); // 10.0 $minorUnits = LaravelWallet::toMinorUnits($wallet, 10.0); // 1000 ``` Common Operations ----------------- [](#common-operations) ### Credit Wallet [](#credit-wallet) ``` LaravelWallet::credit($wallet, 1000, 'payment-ref-123', [ 'description' => 'Payment received', 'source' => 'payment_gateway' ]); ``` ### Debit Wallet [](#debit-wallet) ``` LaravelWallet::debit($wallet, 500, 'purchase-ref-456', [ 'product_id' => 123, 'order_id' => 789 ]); ``` ### Check Balance [](#check-balance) ``` $balance = LaravelWallet::balance($wallet); // Check if sufficient balance exists $hasEnough = LaravelWallet::assertSufficientBalance($wallet, 1000); ``` ### Validate Wallet Integrity [](#validate-wallet-integrity) ``` $validation = LaravelWallet::validateWallet($wallet); if (!$validation['valid']) { // Wallet has been tampered with // Automatically frozen by the package } ``` ### Freeze/Unfreeze Wallet [](#freezeunfreeze-wallet) ``` // Freeze wallet (prevents all operations) LaravelWallet::freeze($wallet, 'Suspicious activity detected'); // Unfreeze wallet LaravelWallet::unfreeze($wallet, 'Issue resolved'); ``` ### QR Payments [](#qr-payments) ``` // Generate QR payment $qrPayment = LaravelWallet::generateQrPayment( $wallet, 1000, 'Payment for order #123', 30 // expires in 30 minutes ); // Process QR payment $result = LaravelWallet::processQrPayment( $payerWallet, $qrPayment['qr_code'] ); ``` ### Wallet Profile [](#wallet-profile) ``` $profile = LaravelWallet::profile($wallet); // Returns comprehensive wallet information: // - Balance // - Currency // - Status // - Transaction count // - Last transaction // - Conversion rate // - Services enabled ``` Advanced Features ----------------- [](#advanced-features) ### Rate Limiting [](#rate-limiting) Prevent abuse by setting rate limits on wallet operations: ``` LaravelWallet::setRateLimit($wallet, 'credit', 10, 'hour'); // 10 credits per hour LaravelWallet::setRateLimit($wallet, 'debit', 20, 'day'); // 20 debits per day ``` ### Wallet Services [](#wallet-services) Enable or disable specific services for a wallet: ``` LaravelWallet::enableService($wallet, 'transfers'); LaravelWallet::enableService($wallet, 'qr_payments'); LaravelWallet::disableService($wallet, 'external_credits'); ``` ### Password Protection [](#password-protection) Add an extra layer of security with wallet passwords: ``` LaravelWallet::password($wallet, 'secure-password-123', [ 'require_for_debit' => true, 'require_for_transfer' => true ]); ``` ### External Credits [](#external-credits) Use `sendCredit()` for system/external credits that bypass rate limits: ``` LaravelWallet::sendCredit($wallet, 1000, 'system-bonus', [ 'type' => 'referral_bonus', 'campaign_id' => 456 ]); ``` Exception Handling ------------------ [](#exception-handling) The package provides specific exceptions for better error handling: ``` use Zfhassaan\LaravelWallet\Exceptions\WalletTamperedException; use Zfhassaan\LaravelWallet\Exceptions\RateLimitExceededException; try { LaravelWallet::debit($wallet, 1000); } catch (WalletTamperedException $e) { // Wallet integrity compromised } catch (RateLimitExceededException $e) { // Rate limit exceeded } catch (InsufficientBalanceException $e) { // Not enough balance } ``` Configuration ------------- [](#configuration) After publishing the configuration file, you can customize various settings: ``` // config/laravel-wallet.php return [ 'default_currency' => 'PKR', 'default_conversion_rate' => 100, 'tables' => [ 'wallets' => 'wallets', 'transactions' => 'wallet_transactions', // ... other tables ], 'rate_limiting' => [ 'enabled' => true, 'default_limit' => 100, 'default_period' => 'hour', ], // ... more configuration options ]; ``` Testing ------- [](#testing) Run the test suite: ``` composer test ``` Or with PHPUnit directly: ``` vendor/bin/phpunit ``` Documentation ------------- [](#documentation) Complete documentation is available in the `docs/` directory. You can also view it online by serving the documentation: ``` cd docs php -S localhost:8000 ``` Then visit `http://localhost:8000` in your browser. Contributing ------------ [](#contributing) Contributions are welcome! Please feel free to submit a Pull Request. 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add some amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request Security -------- [](#security) If you discover any security-related issues, please email instead of using the issue tracker. License ------- [](#license) This package is open-sourced software licensed under the [MIT license](LICENSE). Support ------- [](#support) - **GitHub Issues**: [Report a bug or request a feature](https://github.com/zfhassaan/laravel-wallet/issues) - **Packagist**: [View on Packagist](https://packagist.org/packages/zfhassaan/laravel-wallet) Credits ------- [](#credits) - **Author**: [Hassaan Ali](https://github.com/zfhassaan) - **Package**: Laravel Wallet --- Built with ❤️ for the Laravel community ### Health Score 18 — LowBetter than 8% of packages Maintenance54 Moderate activity, may be stable Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity12 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/3f91e22a64582fa1db957f7f189736d6cd2e6f1f69c2236a42a9ee8fcbdd0723?d=identicon)[zfhassaan](/maintainers/zfhassaan) --- Top Contributors [![zfhassaan](https://avatars.githubusercontent.com/u/17079656?v=4)](https://github.com/zfhassaan "zfhassaan (43 commits)") --- Tags digitalframeworklaravelphp8wallet ### Embed Badge ![Health badge](/badges/zfhassaan-laravel-wallet/health.svg) ``` [![Health](https://phpackages.com/badges/zfhassaan-laravel-wallet/health.svg)](https://phpackages.com/packages/zfhassaan-laravel-wallet) ``` ### Alternatives [omnipay/paypal PayPal gateway for Omnipay payment processing library 3156.8M53](/packages/omnipay-paypal)[eduardokum/laravel-boleto Biblioteca com boletos para o laravel 626351.9k2](/packages/eduardokum-laravel-boleto)[tbbc/money-bundle This is a Symfony bundle that integrates moneyphp/money library (Fowler pattern): https://github.com/moneyphp/money. 1961.9M](/packages/tbbc-money-bundle)[2checkout/2checkout-php 2Checkout PHP Library 83740.3k2](/packages/2checkout-2checkout-php)[smhg/sepa-qr-data Generate QR code data for SEPA payments 61717.2k5](/packages/smhg-sepa-qr-data)[omnipay/dummy Dummy driver for the Omnipay payment processing library 271.2M33](/packages/omnipay-dummy) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)