README

Installation

To install the MoneyMan package, follow these steps:

1. Require the package via Composer:

   composer require vp-trading/moneyman

2. Publish the configuration, route, and migration files:

   php artisan vendor:publish --provider="Vptrading\MoneyMan\MoneyManServiceProvider"

   The package comes with a config files to help you get started quickly.

3. Configure your .env file:

   Add your Providers API keys:

   MONEYMAN_REF_PREFIX=
   
   MONEYMAN_CHAPA_SECRET_KEY=
   MONEYMAN_CHAPA_BASE_URL=
   MONEYMAN_CHAPA_CALLBACK_URL=
   MONEYMAN_CHAPA_WEBHOOK_SECRET=
   
   MONEYMAN_SANTIMPAY_BASE_URL=
   MONEYMAN_SANTIMPAY_PUBLIC_KEY=
   MONEYMAN_SANTIMPAY_PRIVATE_KEY=
   MONEYMAN_SANTIMPAY_MERCHANT_ID=
   MONEYMAN_SANTIMPAY_TOKEN=
   MONEYMAN_SANTIMPAY_CALLBACK_URL=
   
   MONEYMAN_TELEBIRR_MERCHANT_APP_ID=
   MONEYMAN_TELEBIRR_FABRIC_APP_ID=
   MONEYMAN_TELEBIRR_SHORT_CODE=
   MONEYMAN_TELEBIRR_APP_SECRET=
   MONEYMAN_TELEBIRR_PRIVATE_KEY=
   MONEYMAN_TELEBIRR_BASE_URL=
   MONEYMAN_TELEBIRR_TIMEOUT=
   MONEYMAN_TELEBIRR_CALLBACK_URL=
   MONEYMAN_TELEBIRR_WEB_BASE_URL=
   
   MONEYMAN_BOA_USSD_BASE_URL=
   MONEYMAN_BOA_USSD_CLIENT_ID=
   MONEYMAN_BOA_USSD_CLIENT_SECRET=
   MONEYMAN_BOA_USSD_REFRESH_TOKEN=
   MONEYMAN_BOA_USSD_MERCHANT_NAME=
   MONEYMAN_BOA_USSD_MERCHANT_ACCOUNT=
   MONEYMAN_BOA_USSD_API_KEY=

4. Ready to use!

   You can now use the package in your Laravel application.

Support

Usage

Before you start using this package you should know all amount must be put in cent values. The development of this package took standards from Stripe. So for example if you want the amount be 100 Birr you will put 10000.

Here are some basic usage examples:

Initialize Payment

use Vptrading\MoneyMan\MoneyMan;
use Vptrading\MoneyMan\Enums\Provider;
use Vptrading\MoneyMan\ValueObjects\User;
use Money\Money;

$response = MoneyMan::provider(Provider::Chapa)->initiate([
    Money::ETB(10000),
    new User(
        firstName: 'John',
        lastName: 'Doe',
        email: 'johndoe@example.com',
        phoneNumber: '0912345678'
    ),
    route('return-url')
]);

// Redirect user to payment page
return redirect($response->checkoutUrl);

The initiate response is a DTO that consists of the status of of the request, message if the provider has one, transactionId, and checkoutUrl if the request was successful.

For telebirr you will need to wrap the checkoutUrl provided in an <a> tag for it to work or else you will see an error: "Payment cannot be completed. The required parameter of the request is empty, or the parameter is incorrectly filled."

For BoaUssd, there is no checkoutUrl because it is a USSD flow. The provider returns once the user PIN interaction is completed on the phone.

Verify Payment

use Vptrading\MoneyMan\MoneyMan;
use Vptrading\MoneyMan\Enums\Provider;
use Money\Money;

$response = MoneyMan::provider(Provider::Chapa)->verify($transactionId);

The verify response is a DTO that consists of the status of of the request, message if the provider has one, transactionId, and data which is the response from the provider.

For BoaUssd, pass the billNumber (reference) returned during initiate as the transactionId to verify(). The package verifies using GET /ussd/push/getStatus?reference={billNumber}.

BoaUssd tokens are persisted in the boa_tokens table and are encrypted at rest using Laravel encrypted model casts. On expired access token / 401, the package refreshes with refresh token and retries once automatically.

Refund Payment

use Vptrading\MoneyMan\MoneyMan;
use Vptrading\MoneyMan\Enums\Provider;
use Money\Money;

$response = MoneyMan::provider(Provider::Chapa)->refund($transactionId, Money::ETB(1000));

The refund response is a DTO that consists of the status of of the request, message if the provider has one, transactionId, and data which is the response from the provider.

Note: Chapa's refund does not use the transactionId you provided but instead the reference Id they assign to the transaction.