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.