README

A lightweight, plug-and-play Laravel package for managing virtual wallets, supporting multiple wallet types, transaction logs, and seamless integration with any model like User.

🚀 Features

💼 Multi-Wallet Support — Create and manage multiple wallet types per user.
📜 Transaction Management — All wallet operations are recorded for full traceability.
💳 Payment Processing — Seamlessly handle payments between wallets or external systems.
🏦 Deposit Handling — Accept and log deposits from users or third-party services.
🌍 Multiple Currency Support — Manage wallet balances in different currencies with ease.
📶 Wallet Status Tracking — Monitor and update wallet statuses like active, frozen, or closed.
🔐 Secure & Reliable — Built using Laravel's Eloquent, enums, morphs & policy-friendly structure.
⚙️ Highly Configurable — Override models, table names, and more via config.
🧩 Easy Integration — Just use a trait on your model and you're ready to go.
💸 Balance Management — Simple credit, debit, transfer, and balance APIs.

📦 Installation

composer require haxneeraj/laravel-virtual-wallet
php artisan vendor:publish --provider="Haxneeraj\LaravelVirtualWallet\LaravelVirtualWalletServiceProvider"
php artisan migrate

🔧 Configuration

After publishing the config file, you can modify config/laravel-virtual-wallet.php to override models, table names, and enums if needed.

📥 Setup in Your Model

Add the trait and implement the interface in your User (or any Eloquent model):

use Haxneeraj\LaravelVirtualWallet\Interfaces\WalletInterface;
use Haxneeraj\LaravelVirtualWallet\Traits\HasVirtualWallet;

class User extends Authenticatable implements WalletInterface
{
    use HasVirtualWallet;
}

💡 Usage

Create Wallets

$user->wallets()->create([
    'wallet_type' => 'main', // Type of wallet (e.g., 'main', 'bonus', 'savings'). Define these in your WalletType enum.
    'currency' => 'usd', // ISO currency code. Ensure 'usd' or your required currencies are defined in your Currency enum.
    'balance' => 100, // Initial wallet balance. Usually set to 0 or default starting value.
    'currency_type' => 'fiat_currency', // Define whether the currency is fiat, crypto, token, etc. Set values in CurrencyType enum.
    'status' => 'active' // Current status of wallet (e.g., 'active', 'frozen', 'closed'). Defined in WalletStatus enum.
]);

Deposit

$paymentData = new PaymentData([
    'owner_type' => User::class,
    'owner_id' => $this->user->id,
    'txid' => 'test-txid',
    'amount' => 100,
    'description' => 'Test deposit',
    'wallet_type' => 'wallet1',
    'method' => 'automatic',
    'transaction_type' => 'deposit',
    'status' => 'approved',
    'currency' => 'usd',
    'currency_type' => 'fiat_currency'
]);
$user->deposit($paymentData);

Withdraw

$paymentData = new PaymentData([
    'owner_type' => User::class,
    'owner_id' => $this->user->id,
    'txid' => 'test-txid-withdraw1',
    'amount' => 50,
    'description' => 'Test withdrawal',
    'wallet_type' => 'wallet1',
    'method' => 'automatic',
    'transaction_type' => 'withdraw',
    'status' => 'approved',
    'currency' => 'usd',
    'currency_type' => 'fiat_currency'
]);
$user->pay($paymentData);

Get Balance

$balance = $user->getBalance('main');

Check Balance

$user->hasSufficientBalance(50, 'main');

Available Methods

Wallet Management

Method	Parameters	Returns	Description
`wallets()`	`string $walletType = null`	`MorphMany`	Get all wallets or filter by type
`getBalance()`	`string $walletType = null`	`int OR float`	Get wallet balance
`hasBalance()`	`string $walletType = null`	`bool`	Check if wallet has positive balance
`hasSufficientBalance()`	`int OR float $amount, string $walletType = null`	`bool`	Check if wallet has sufficient balance

Payment Processing

Method	Parameters	Returns	Description
`pay()`	`PaymentData $paymentData`	`void`	Process payment from wallet(s)

Deposit Handling

Method	Parameters	Returns	Description
`deposit()`	`PaymentData $paymentData`	`void`	Deposit funds into wallet

Data Objects

PaymentData

The PaymentData object is used for both payments and deposits. It accepts the following parameters:

owner_type: Owner model type
owner_id: Owner model ID
amount: The amount to process
wallet_type: Type of wallet (optional)
description: Transaction description
status: Transaction status
method: Payment method
transaction_type: Type of transaction
txid: Transaction ID

Exceptions

The package throws the following exceptions:

InvalidWalletException: When wallet type is invalid or wallet not found
InsufficientBalanceException: When wallet balance is insufficient

⚙️ Testing

This package comes with feature and unit tests to ensure everything works smoothly.

🏃 Run Tests

composer test

🤝 Contributing

Contributions, issues and feature requests are welcome!

Fork it
Create your feature branch (git checkout -b feature/awesome)
Commit your changes (git commit -am 'Add something awesome')
Push to the branch (git push origin feature/awesome)
Create a new Pull Request

🧠 Author

Neeraj Saini
📧 hax-neeraj@outlook.com
🌐 https://github.com/haxneeraj/laravel-virtual-wallet

📄 License

Licensed under the MIT License.

haxneeraj / laravel-virtual-wallet

Maintainers

Details