README

此模块使得与 Paybox 支付网关的集成变得更容易。它目前支持使用Paybox系统进行两种支付方式。

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

安装

1. 在控制台中运行

   composer require bnbwebexpertise/laravel-paybox-gateway

   以安装此模块

2. 对于Laravel < 5.5，打开 config/app.php 并在 providers 部分添加

   Bnb\PayboxGateway\Providers\PayboxServiceProvider::class,

   您还需要发布迁移文件

       php artisan vendor:publish --provider="Bnb\PayboxGateway\Providers\PayboxServiceProvider" --tag=migrations

3. 运行迁移

       php artisan migrate

4. 如果您需要进行高级定制，请在您的控制台中运行

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

   以发布默认配置文件和示例视图

5. 打开 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(\Bnb\PayboxGateway\Requests\AuthorizationWithCapture::class);

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

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

在上面的示例代码中，已进行全额付款。如果您只想授权付款（您将在以后捕获），则应使用AuthorizationWithoutCapture类代替AuthorizationWithCapture。

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

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

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

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

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

定义客户返回路由

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

处理事务验证路由

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

$payment = Payment::where('number', $request->input('order_number'))->firstOrFail();
$payboxVerify = \App::make(\Bnb\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天的时间来完成此操作，超过此延迟，您可能失去反欺诈保证，请联系您的Paybox提供商以获取适当的用法信息）。

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

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

对于setPayboxCallNumber和setPayboxTransactionNumber，您应使用在处理处理事务验证路由步骤中收到的值，因此您可能需要在此步骤中保存它们以在此处使用。

许可证

此软件包受MIT许可证许可。