README

[英文]

此模块使得与Paybox支付网关的集成更加简单。它目前支持使用Paybox系统进行支付的两个方式。

1. 通过Paybox系统完成全额支付 - 这是接收支付的最常见方式 - 客户需要为其订单支付，支付后您可以处理订单
2. 通过Paybox系统进行授权，然后通过Paybox Direct进行捕获 - 客户首先进行支付，但实际上并未完成支付，支付只是被授权。在最多7天的期限内，您需要确认您想要/能够处理订单并捕获支付。在成功捕获支付后，您可以处理订单。

[法语]

此模块使得在Laravel（6.0+）项目中轻松集成Paybox支付解决方案。

安装

1. Composer

   composer require devpark/laravel-paybox-gateway

   在控制台中安装此模块

2. 打开 config/app.php 并添加

   Devpark\PayboxGateway\Providers\PayboxServiceProvider::class,

   到 providers 部分

3. 运行

   php artisan vendor:publish --provider="Devpark\PayboxGateway\Providers\PayboxServiceProvider"

   以发布配置文件

4. 打开 config/paybox.php 并根据您的需求进行配置。默认情况下，您应该在您的 .env 文件中将以下变量放入并使用有效的值

• PAYBOX_TEST - 是否使用Paybox测试系统（仅在进行测试时设置为 true），
• PAYBOX_SITE - Paybox提供的站点号
• PAYBOX_RANK - Paybox提供的排名号
• PAYBOX_ID - Paybox提供的内部标识符
• PAYBOX_BACK_OFFICE_PASSWORD - Paybox后台办公室密码。如果您打算进行 Capture 请求，则此密码是必需的。否则，不建议填写它（它将不会被使用）
• PAYBOX_HMAC_KEY - 这是您应该在Paybox后台办公室生成的密钥

1. 下载 Paybox公钥 并将其放置在 config/paybox.php 中指定的目录和名称下，作为 public_key 键

2. 在您的路由文件中注册具有您在 config/paybox.php 的 customer_return_routes_names 和 transaction_verify_route_name 组中定义的名称的路由

用法

为了使用该系统，您需要做一些事情

1. 您需要启动授权请求以初始化支付

2. 您需要处理客户返回的路由以向客户显示消息。默认情况下，根据交易的最终情况，有4种不同的路由。请注意，您永远不应该使用这些路由来更改支付状态，因为这在这个阶段并不完全确定。您应该使用处理交易的路线来完成此操作

3. 您应该处理交易验证路由。在这里，您应该在收到请求后更改支付状态并执行任何其他操作。

4. 如果您想要捕获先前授权的支付，您也应该处理捕获先前支付。

授权请求

这是您需要启动以初始化支付的主要请求。

授权请求的最基本示例代码可能看起来像这样

$authorizationRequest = \App::make(\Devpark\PayboxGateway\Requests\AuthorizationWithCapture::class);

return $authorizationRequest->setAmount(100)->setCustomerEmail('test@example.com')
            ->setPaymentNumber(1)->send('paybox.send');

此代码应在控制器中运行，因为它返回视图，默认情况下会自动将客户重定向到Paybox网站。

在上面的示例代码中，进行了全额支付。如果您只想授权支付（稍后您将捕获它），则应使用 AuthorizationWithoutCapture 类而不是 AuthorizationWithCapture

如果您需要更多定制，请查看 \Devpark\PayboxGateway\Requests\Authorization 类的公共方法。

对于 setAmount 方法，默认货币为欧元。如果您想使用其他货币，应使用 \Devpark\PayboxGateway\Currency 类中的货币常量作为第二个参数。同时请注意，您应提供给此函数的实际金额（带小数位）而不是已转换为 Paybox 格式的金额。

对于 setPaymentNumber，您应确保此处提供的号码对于每次调用都是唯一的。这就是为什么您可能需要为每个订单创建付款表，并且根据您的系统，您可能需要假设订单有多笔付款（例如，有人最初取消订单，但后来如果给了他这样的选项，他们决定再次付款）。

在这个步骤中，您可能还需要调整发送请求的视图，因为在某些情况下，它可能会被客户端看到。但是，您不应在此步骤中更改发送给 Paybox 的字段，否则它将无法工作。

如果您使用 AuthorizationWithoutCapture，请确保您的返回字段中有 \Devpark\PayboxGateway\ResponseField::PAYBOX_CALL_NUMBER 和 \Devpark\PayboxGateway\ResponseField::TRANSACTION_NUMBER，因为那些值在稍后捕获付款时将被需要。您还应该始终在返回字段中有 \Devpark\PayboxGateway\ResponseField::AUTHORIZATION_NUMBER 和 \Devpark\PayboxGateway\ResponseField::SIGNATURE，并且签名应该是最后一个参数。

定义客户返回路由

默认情况下创建了4个具有示例英文文本的示例视图。您应创建显示这些视图的路由（这些路由将使用 GET HTTP 方法启动），调整这些视图，在大多数情况下这已经足够，因为实际的支付状态将通过事务验证路由进行验证。

处理事务验证路由

为了确保付款真正成功，您应使用 \Devpark\PayboxGateway\Responses\Verify 类。最简单的代码可能如下所示

$payment = Payment::where('number', $request->input('order_number'))->firstOrFail();
$payboxVerify = \App::make(\Devpark\PayboxGateway\Responses\Verify::class);
try {
    $success = $payboxVerify->isSuccess($payment->amount);
    if ($success) {
       // process order here after making sure it was real payment
    }
    echo "OK";
}
catch (InvalidSignature $e) {
    Log::alert('Invalid payment signature detected');
}

此代码应在控制器中运行，因为当收到有效的 Paybox 事务验证路由请求时，您应返回非空响应。如您所见，首先您需要按号码查找订单，然后您需要确保它是成功的。如果是，您应确保它是一个真实的付款，然后您才能处理订单（如果使用全额付款，则始终为真，但在您的应用程序中也使用授权仅付款且稍后捕获的情况下，您应确保您不会处理授权仅付款的订单）。

捕获先前授权的请求

如果您使用 Paybox 系统授权后通过 Paybox Direct 捕获，您最终将捕获先前授权的付款（您有最多 7 天的时间来做这件事）。

最简单的代码可能如下所示

$payment = PaymentModel::find($idOfAuthorizedPayment);
$captureRequest = \App::make(\Devpark\PayboxGateway\Requests\Capture::class);
$response = $captureRequest->setAmount($payment->amount)
                           ->setPayboxCallNumber($payment->call_number)
                           ->setPayboxTransactionNumber($payment->transaction_number)
                           ->setDayRequestNumber(2)
                           ->send();
                           
if ($response->isSuccess()) {
     // process order here                
}

在上面的代码中，您应确保您为 setDayRequestNumber 提供的值是当天从 1 到 2147483647 的唯一数字。对于 setPayboxCallNumber 和 setPayboxTransactionNumber，您应使用在处理 处理事务验证路由 步骤中收到的值，因此您可能需要在此步骤中保存它们以在此处使用。

许可证

此软件包根据 MIT 许可证 许可。