README

A powerful package for Laravel that facilitates seamless management of virtual currency, transaction handling, balance management, and fund transfers within your applications.

Features

Wallet Management: Create and manage wallets associated with users or other entities.
Payment Handling: Manage payments, including initiation, processing, and transaction logging.
Transaction Management: Record and track all wallet-related transactions, including deposits and withdrawals.
Configurable Withdraw Ceiling: Set a ceiling limit for withdrawals through configuration.

Requirements:

Laravel Version: 10 or higher
PHP Version: 8.0 or higher

Installation

To install the package, use Composer:

composer require ars/laravel-cashier

After installation, publish the configuration and migration files:

php artisan vendor:publish --provider="Ars\Cashier\Providers\CashierServiceProvider"

Then, run the migrations:

php artisan migrate

Configuration

The package comes with a configuration file located at config/cashier.php. Key configuration options include:

wallet.ceiling_withdraw: The default withdrawal ceiling.
tables: Customizable table names for wallets, payments, and transactions.

return [
    'wallet' => [
        'ceiling_withdraw' => 0,
    ],
    'tables' => [
        'wallet' => 'wallets',
        'payment' => 'payments',
        'transaction' => 'transactions',
    ],
];

Usage

Traits

HasWallet

Add the HasWallet trait to any model that should have a wallet:

use Ars\Cashier\Models\Traits\HasWallet;

class User extends Model
{
    use HasWallet;
}

Get Balance: Retrieve the wallet balance with:
```
$balance = $user->balance;
```
Deposit:
```
$user->deposit(100, ['description' => 'Initial deposit']);
```
This will increase the user’s wallet balance by 100 and log the transaction.
Withdraw:
```
$user->withdraw(50, ['description' => 'Purchase withdrawal']);
```
This will decrease the user’s wallet balance by 50, if within the allowable ceiling, and log the transaction.

Check Withdraw Capability:

if ($user->canWithdraw(50, 10)) {
    echo "Withdrawal allowed";
} else {
    echo "Withdrawal exceeds allowed limits";
}

HasPay

Add the HasPay trait to any model that should handle payments:

use Ars\Cashier\Models\Traits\HasPay;

class Order extends Model
{
    use HasPay;
}

Initiate Payment:

$payment = $order->requestPay('AUTH123', 200, ['order_id' => $order->id]);

This starts a payment process and logs it as a transaction.

Process Payment Result:
```
$result = $order->resultPay('AUTH123', '00', 'REF456');
```
This updates the payment details and marks the associated transaction as accepted.
Access Payment Transaction:
```
$transaction = $payment->transaction;
```
You can access the transaction associated with a specific payment.

Wallet Model

The Wallet model manages user balances and transactions.

Get All Transactions:

$transactions = $wallet->transactions;
foreach ($transactions as $transaction) {
    echo $transaction->amount . " - " . $transaction->type;
}

Set Custom Withdrawal Ceiling:
```
$wallet->ceilingWithdraw = 500;
```
You can dynamically adjust the ceiling for withdrawals on a specific wallet.

Payment Model

The Payment model handles payment processing and recording.

Retrieve Payment by Authority:
```
$payment = Payment::where('authority', 'AUTH123')->first();
```
This retrieves a payment record based on its authority code.
Update Payment Status:
```
$payment->update(['status_code' => '00', 'payed_at' => now()]);
```
This updates the status of a payment, which can be useful in payment processing callbacks.

License

This package is open-sourced software licensed under the MIT license.

Contributing

Contributions are welcome! Please submit a pull request or create an issue for any improvements or suggestions.

Support

For any issues, please visit the Issues page.

ars / laravel-cashier

Maintainers

Details