README

Simplify the integration of Ecash payments into your Laravel applications. This package offers a streamlined setup and intuitive API to process payments quickly and securely.

Installation

You can install the package via composer:

composer require alhelwany/laravel-ecash

You can publish and run the migrations with:

php artisan vendor:publish --tag="laravel-ecash-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="laravel-ecash-config"

This is the contents of the published config file:

return [
    'gatewayUrl' => env('ECASH_GATEWAY_URL', 'https://checkout.ecash-pay.co'),
    'terminalKey' => env('ECASH_TERMINAL_KEY', null),
    'merchantId' => env('ECASH_MERCHANT_ID', null),
    'merchantSecret' => env('ECASH_MERCHANT_SECRET', null),
];

Getting Started

Setup your environment variables
Publish and run the migrations
To start the payment process, use the checkout method to create a payment model & generate the payment URL
Once the payment is complete, and the gateway redirects the user to the redirect URL, the payment status changes from PENDING to PROCESSING
Once the gateway calls the callback URL, the payment status Changes from PROCESSING to either FAILED or PAID
On each payment status change, a PaymentStatusUpdated event is fired, you may configure a listener to update the status of your order

Enums

Enums are in the namespace "Alhelwany\LaravelEcash\Enums"

enum Lang: string
{
    case AR = 'AR';
    case EN = 'EN';
}

enum Currency: string
{
    case SYP = 'SYP'; // The only available currency by the gateway so far 
}

enum CheckoutType: string
{
    case QR = 'QR';
    case CARD = 'Card';
}

enum PaymentStatus: string
{
    case PENDING = 'pending';
    case PROCESSING = 'processing';
    case PAID = 'paid';
    case FAILED = 'failed';
}

Exceptions

InvalidAmountException

Thrown when the checkout function is called with negative or 0 amount.

InvalidConfigurationException

Thrown when trying to use the package before setting up the .env variables

Events

PaymentStatusUpdated

namespace Alhelwany\LaravelEcash\Events;

use Illuminate\Broadcasting\InteractsWithSockets;
use Illuminate\Foundation\Events\Dispatchable;
use Illuminate\Queue\SerializesModels;
use Alhelwany\LaravelEcash\Models\EcashPayment;

class PaymentStatusUpdated
{
    use Dispatchable, InteractsWithSockets, SerializesModels;

    public function __construct(private EcashPayment $paymentModel)
    {
    }

    public function getPaymentModel(): EcashPayment
    {
        return $this->paymentModel;
    }
}

Important Note

The EcashPayment Model uses id of type UUID as a primary key

Example Usage

Checkout

use App\Http\Controllers\Controller;

use Alhelwany\LaravelEcash\Facades\LaravelEcashClient;
use Alhelwany\LaravelEcash\DataObjects\PaymentDataObject;
use Alhelwany\LaravelEcash\Models\EcashPayment;
use Alhelwany\LaravelEcash\Enums\CheckoutType;
use Alhelwany\LaravelEcash\Enums\Lang;
use Alhelwany\LaravelEcash\Enums\Currency;

class ExampleController extends Controller
{
    public function checkout($request)
    {
        $paymentDataObject = new PaymentDataObject(CheckoutType::CARD, 100.10);

        $paymentDataObject->setRedirectUrl(route('payment-successful')); //optional
        $paymentDataObject->setLang(Lang::EN); //optional
        $paymentDataObject->setCurrency(Currency::SYP); //optional

        $model = LaravelEcashClient::checkout($paymentDataObject);

        // You may attach the EcashPayment model to your order
        return redirect($model['checkout_url']);
    }
}

Testing

composer test

Credits

Mhd Ghaith Alhelwany

License

The MIT License (MIT). Please see License File for more information.

alhelwany / laravel-ecash

Maintainers

Details