Al Rajhi Bank payment gateway API wrapper (ARB)

This package is a wrapper around the Al Rajhi Bank payment gateway API, it allows you to initiate a payment request hosted on the Bank website or on the merchant website, and also allows you to refund a payment.

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Installation

You can install the package via composer:

composer require alaa-elsaid/arb

You can publish the config file with:

php artisan vendor:publish --tag="arb-config"

This is the contents of the published config file:

return [
    'mode' => env('ARB_MODE', 'test'), // test or live
    'test_merchant_endpoint' => 'https://securepayments.alrajhibank.com.sa/pg/payment/tranportal.htm',
    'live_merchant_endpoint' => 'https://digitalpayments.alrajhibank.com.sa/pg/payment/tranportal.htm',
    'test_bank_hosted_endpoint' => 'https://securepayments.alrajhibank.com.sa/pg/payment/hosted.htm',
    'live_bank_hosted_endpoint' => 'https://digitalpayments.alrajhibank.com.sa/pg/payment/hosted.htm',
    'tranportal_id' => env('ARB_TRANPORTAL_ID'),
    'tranportal_password' => env('ARB_TRANPORTAL_PASSWORD'),
    "resource_key" => env('ARB_RESOURCE_KEY'), // your resource key
    "currency_code" => env('ARB_CURRENCY_CODE', '682'),
];

add the following to your .env file

Usage

Bank hosted payment

to initiate a payment request hosted on the Bank website

use Alaa\Arb\Facades\Arb;
    
    
$responce = Arb::initiatePayment(100); // 100 to be paid

dd($responce);
/** @example
{#
  +"success": true
  +"url": "https://securepayments.alrajhibank.com.sa/pg/paymentpage.htm?PaymentID=?paymentId=000000000000000000"
}
*/

merchant hosted payment

to initiate a payment request hosted on the merchant website, you need to create a form for the card details, and pass the card details to the Arb::card() method, then call the Arb::initiatePayment() method as shown below

use Alaa\Arb\Facades\Arb;
use Alaa\Arb\Objects\Card;
    

Arb::card([
   'number' => '5105105105105100',
   'year' => '20'.'24',
   'month' => '12',
   'name' => 'AbdulRahman',
   'cvv' => '123',
   'type' => Card::CREDIT // or Card::DEBIT
]);    
$responce = Arb::initiatePayment(100); // 100 to be paid

dd($responce);
/** @example
{#
  +"success": true
  +"url": "https://securepayments.alrajhibank.com.sa/pg/payment/hosted.htm?paymentId=000000000000000000&id=000x0bAdcEF0HfZ"
}
*/

Refund a payment

to refund a payment you need to call the Arb::refund() method as shown below

use Alaa\Arb\Facades\Arb;

$responce = Arb::refund('000000000000000000', 100); // 100 to be refunded

dd($responce);
/** @example
{#
  +"success": true
  +"data": {}
}
*/

manage data sent & received from the bank

to send custom data to the bank, you can use the Arb::data() method before any transaction as shown below

use Alaa\Arb\Facades\Arb;
Arb::data([
    'request_id' => 23,
    'user_id' => 43,
]);
// initiate a payment or make a refund

this data will be sent to the bank and will be returned in the response from the bank, ArbPaymentSuccessEvent will be fired with the received data from the bank as shown below

use Alaa\Arb\Events\ArbPaymentSuccessEvent;

Event::listen(ArbPaymentSuccessEvent::class, function (ArbPaymentSuccessEvent $event) {
    $response = $event->response;
    // to get the data sent to the bank
    $data = $response->getOriginalData();
});

Note: you can listen to the ArbPaymentSuccessEvent in both ways: EventServiceProvider::$listen or Event::listen() method

Handle the response

egyjs/arb has a built-in event driven architecture (EDA) system to handle the response from the bank; you can listen to the ArbPaymentSuccessEvent event to handle the success response, and the ArbPaymentFailedEvent event to handle the fail response,

The use of events allows for decoupling between the processing logic and the actions taken upon success or failure. By emitting events, the processing logic doesn't need to know about or be tightly coupled to the actions taken upon success or failure. you can listen to the events in 2 ways:

1. using the EventServiceProvider class

use Alaa\Arb\Events\ArbPaymentFailedEvent;
use Alaa\Arb\Events\ArbPaymentSuccessEvent;

protected $listen = [
    // ...
    ArbPaymentSuccessEvent::class => [
        LogSuccessArbPaymentListener::class, // add any listener classes you want to handle the success payment
    ],
    ArbPaymentFailedEvent::class => [
        LogFailedArbPaymentListener::class, // add any listener classes you want to handle the failed payment
    ],
];

2. using the Event::listen() method

use Alaa\Arb\Events\ArbPaymentFailedEvent;
use Alaa\Arb\Events\ArbPaymentSuccessEvent;

Event::listen(ArbPaymentSuccessEvent::class, function (ArbPaymentSuccessEvent $event) {
    // handle the success payment
});

Event::listen(ArbPaymentFailedEvent::class, function (ArbPaymentFailedEvent $event) {
    // handle the failed payment
});

handle the response in the controller

if you want to handle the using a custom route instead of the events, you can pass the success and fail urls to the Arb::successUrl() and Arb::failUrl() methods as shown below

use Alaa\Arb\Facades\Arb;

Arb::successUrl('http://localhost:8000/arb/response')
    ->failUrl('http://localhost:8000/arb/response');
$responce = Arb::initiatePayment(100); // 100 to be paid

dd($responce);
/** @example
{#
  +"success": true
  +"url": "http://localhost:8000/success/handle?paymentId=000000000000000000"
}
*/

your /routes/web.php file should look like this

use Illuminate\Http\Request;
Route::post('/arb/response', function (Request $request) {
    if ($request->status == 'success') {
        // handle the success payment
    } else {
        // handle the failed payment
    }
});

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• egyjs
• All Contributors

License

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