README

此包是 Al Rajhi 银行支付网关 API 的包装器，允许您在银行网站或商户网站上托管支付请求，并允许您退款。

支持我们

我们投入了大量资源来创建一流的开源包。您可以通过购买我们的付费产品之一来支持我们。

我们非常感谢您从家乡寄给我们明信片，说明您正在使用我们的哪个包。您可以在我们的联系页面上找到我们的地址。我们将发布所有收到的明信片在我们的虚拟明信片墙上。

安装

您可以通过 composer 安装此包

composer require alaa-elsaid/arb

您可以使用以下命令发布配置文件

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

这是发布配置文件的内容

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'),
];

将以下内容添加到您的 .env 文件中

ARB_MODE="test" # test or live
ARB_TRANPORTAL_ID="your_tranportal_id"
ARB_TRANPORTAL_PASSWORD="your_tranportal_password"
ARB_RESOURCE_KEY="your_resource_key"
ARB_CURRENCY_CODE="682" # "682" = SAR 

使用方法

银行托管支付

在银行网站上启动支付请求

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"
}
*/

商户托管支付

在商户网站上启动支付请求，您需要创建一个用于卡详情的表单，并将卡详情传递给 Arb::card() 方法，然后调用以下示例中的 Arb::initiatePayment() 方法

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"
}
*/

退款支付

要退款，您需要调用以下示例中的 Arb::refund() 方法

use Alaa\Arb\Facades\Arb;

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

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

管理发送到银行和从银行接收的数据

要向银行发送自定义数据，您可以在以下示例中的任何交易之前使用 Arb::data() 方法

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

这些数据将发送到银行，并在银行的响应中返回，如下所示，将触发 ArbPaymentSuccessEvent，并带有从银行接收的数据

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();
});

注意：您可以通过以下两种方式监听 ArbPaymentSuccessEvent：在 EventServiceProvider::$listen 或 Event::listen() 方法中

处理响应

egyjs/arb 具有内置的事件驱动架构 (EDA)系统来处理银行的响应；您可以通过监听 ArbPaymentSuccessEvent 事件来处理成功响应，以及监听 ArbPaymentFailedEvent 事件来处理失败响应，

使用事件可以将处理逻辑与成功或失败时的操作解耦。通过发出事件，处理逻辑不需要知道或紧密耦合到成功或失败时的操作。您可以通过以下两种方式监听事件

1. 使用 EventServiceProvider 类

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
    ],
];

1. 使用 Event::listen() 方法

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
});

在控制器中处理响应

如果您想使用自定义路由而不是事件来处理，可以将成功和失败 URL 传递给 Arb::successUrl() 和 Arb::failUrl() 方法，如下所示

use Alaa\Arb\Facades\Arb;

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

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

您的 /routes/web.php 文件应如下所示

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

变更日志

有关最近更改的更多信息，请参阅变更日志

贡献

有关详细信息，请参阅贡献

安全漏洞

请查看我们的安全策略如何报告安全漏洞。

致谢

• egyjs
• 所有贡献者

许可证

MIT 许可证（MIT）。请参阅许可证文件以获取更多信息。