yasserbenaioua / chargily-epay-laravel
A laravel package for chargily epay gateway
Requires
- php: ^8.0
- guzzlehttp/guzzle: ^7.5
- illuminate/contracts: ^8.77|^9.0
- spatie/laravel-package-tools: ^1.9.0
- spatie/laravel-webhook-client: ^3.1.0
Requires (Dev)
- nunomaduro/collision: ^5.5|^6.0
- orchestra/testbench: ^6.24|^7.0
- pestphp/pest: ^1.21
- spatie/pest-plugin-test-time: ^1.0
README
Installation
You can install the package via composer:
composer require yasserbenaioua/chargily-epay-laravel
You must publish the config file with:
php artisan vendor:publish --provider="YasserBenaioua\Chargily\ChargilyServiceProvider" --tag="chargily-config"
This is the contents of the config file that will be published at config/chargily.php
:
use YasserBenaioua\Chargily\Models\ChargilyWebhookCall; return [ /* * Chargily Api Key * You can found it on your epay.chargily.com.dz Dashboard. */ 'key' => env('CHARGILY_API_KEY'), /* * Chargily Api Secret * Your Chargily secret, which is used to verify incoming requests from Chargily. * You can found it on your epay.chargily.com.dz Dashboard. */ 'secret' => env('CHARGILY_API_SECRET'), /* * This is where client redirected after payment processing. */ 'back_url' => 'valid-url-to-redirect-after-payment', /* * This is where you receive payment informations. */ 'webhook_url' => 'valid-url-to-receive-payment-informations', /* * You can define the job that should be run when a chargily webhook hits your application * here. */ 'jobs' => [ // \App\Jobs\HandleChargilyWebhook::class, ], /* * This model will be used to store all incoming webhooks. * It should be or extend `YasserBenaioua\Chargily\Models\ChargilyWebhookCall` */ 'model' => ChargilyWebhookCall::class, /* * When running `php artisan model:prune` all stored Chargily webhook calls * that were successfully processed will be deleted. * * More info on pruning: https://laravel.com/docs/8.x/eloquent#pruning-models */ 'prune_webhook_calls_after_days' => 10, /* * When disabled, the package will not verify if the signature is valid. * This can be handy in local environments. */ 'verify_signature' => env('CHARGILY_SIGNATURE_VERIFY', true), ];
Next, you must publish the migration with:
php artisan vendor:publish --provider="YasserBenaioua\Chargily\ChargilyServiceProvider" --tag="chargily-migrations"
After the migration has been published, you can create the chargily_webhook_calls
table by running the migrations:
php artisan migrate
Finally, take care of the routing: At the chargily config file you must configure at what URL Chargily webhook should be sent. In the routes file of your app you must pass that route to the Route::githubWebhooks
route macro:
Route::chargilyWebhook('webhook-route-configured-at-the-chargily-config-file');
Behind the scenes this macro will register a POST
route to a controller provided by this package. We recommend to put it in the api.php
routes file, so no session is created when a webhook comes in, and no CSRF token is needed.
Should you, for any reason, have to register the route in your web.php
routes file, then you must add that route to the except
array of the VerifyCsrfToken
middleware:
protected $except = [ 'webhook-route-configured-at-the-chargily-config-file', ];
Usage
Firstly, you may create a payment like this:
use YasserBenaioua\Chargily\Chargily; $chargily = new Chargily([ //mode 'mode' => 'EDAHABIA', //OR CIB //payment details 'payment' => [ 'number' => 'payment-number-from-your-side', // Payment or order number 'client_name' => 'client name', // Client name 'client_email' => 'client_email@mail.com', // This is where client receive payment receipt after confirmation 'amount' => 75, //this the amount must be greater than or equal 75 'discount' => 0, //this is discount percentage between 0 and 99 'description' => 'payment-description', // this is the payment description ] ]);
then use getRedirectUrl()
method to get the checkout link:
use YasserBenaioua\Chargily\Chargily; $chargily = new Chargily([ //mode 'mode' => 'EDAHABIA', //OR CIB //payment details 'payment' => [ 'number' => 'payment-number-from-your-side', // Payment or order number 'client_name' => 'client name', // Client name 'client_email' => 'client_email@mail.com', // This is where client receive payment receipt after confirmation 'amount' => 75, //this the amount must be greater than or equal 75 'discount' => 0, //this is discount percentage between 0 and 99 'description' => 'payment-description', // this is the payment description ] ]); $redirectUrl = $chargily->getRedirectUrl(); //like : https://epay.chargily.com.dz/checkout/random_token_here return redirect($redirectUrl);
Chargily will sign all requests hitting the webhook url of your app. This package will automatically verify if the signature is valid.
Unless something goes terribly wrong, this package will always respond with a 200
to webhook requests. All webhook requests with a valid signature will be logged in the chargily_webhook_calls
table. The table has a payload column where the entire payload of the incoming webhook is saved.
If the signature is not valid, the request will not be logged in the chargily_webhook_calls
table but a Spatie\WebhookClient\Exceptions\InvalidWebhookSignature
exception will be thrown. If something goes wrong during the webhook request the thrown exception will be saved in the exception column. In that case the controller will send a 500
instead of 200
.
To handle webhook requests you can define a job that does the work. Here's an example of such a job:
namespace App\Jobs; use Illuminate\Bus\Queueable; use Illuminate\Contracts\Queue\ShouldQueue; use Illuminate\Foundation\Bus\Dispatchable; use Illuminate\Queue\InteractsWithQueue; use Illuminate\Queue\SerializesModels; use Illuminate\Support\Facades\Log; use YasserBenaioua\Chargily\Models\ChargilyWebhookCall; class HandleChargilyWebhook implements ShouldQueue { use Dispatchable, InteractsWithQueue, Queueable, SerializesModels; /** * Create a new job instance. * * @return void */ public function __construct( public ChargilyWebhookCall $webhookCall ) { // } /** * Execute the job. * * @return void */ public function handle() { // do your work here // you can access the payload of the webhook call with `$this->webhookCall->payload` } }
After having created your job you must register it at the jobs
array in the chargily.php
config file.
// config/chargily.php 'jobs' => [ \App\Jobs\HandleChargilyWebhook::class, ],
Deleting processed webhooks
The YasserBenaioua\Chargily\Models\ChargilyWebhookCall
is MassPrunable
. To delete all processed webhooks every day you can schedule this command.
$schedule->command('model:prune', [ '--model' => [\YasserBenaioua\Chargily\Models\ChargilyWebhookCall::class], ])->daily();
Testing
composer test
Changelog
Please see CHANGELOG for more information on what has changed recently.
Credits
License
The MIT License (MIT). Please see License File for more information.