julienmru/laravel-paybox-gateway

Laravel Paybox网关

维护者

详细信息

github.com/julienmru/laravel-paybox-gateway

源代码

安装：2,773

依赖项: 0

建议: 0

安全性: 0

星星: 0

关注者: 1

分支: 10

1.5.2 2024-02-07 11:54 UTC

Requires

Requires (Dev)

MIT b63a4f31ce98b5ec87aeccc494770ea4eb04f1b9

This package is auto-updated.

Last update: 2024-09-07 13:12:50 UTC

README

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

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

安装

  1. 运行

    composer require julienmru/laravel-paybox-gateway

    在控制台中安装此模块

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

    JulienMru\PayboxGateway\Providers\PayboxServiceProvider::class,

    在 providers 部分

  3. 运行

    php artisan vendor:publish --provider="JulienMru\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(\JulienMru\PayboxGateway\Requests\AuthorizationWithCapture::class);

return $authorizationRequest->setAmount(100)->setCustomer([
                            'firstname' => 'John',
                            'lastname' => 'Doe',
                            'email' => 'john.doe@example.com',
                            'address' => 'Test Street',
                            'postcode' => '75015',
                            'city' => 'PARIS',
                            'countrycode' => 250 // ISO Numeric Code
                        ])
            ->setShoppingCart(['total' => ['totalQuantity' => 10]])
            ->setPaymentNumber(1)->send('paybox.send');

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

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

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

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

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

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

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

订阅请求

这是您需要启动以初始化定期付款（例如，用于订阅）的请求。

订阅请求的最基本示例代码可能如下所示

$subscriptionRequest = \App::make(\JulienMru\PayboxGateway\Requests\Subscription::class);

return $subscriptionRequest->setInitialAmount(100)->setRecurringAmount(100)->setCustomer([
                            'firstname' => 'John',
                            'lastname' => 'Doe',
                            'email' => 'john.doe@example.com',
                            'address' => 'Test Street',
                            'postcode' => '75015',
                            'city' => 'PARIS',
                            'countrycode' => 250 // ISO Numeric Code
                        ])
            ->setShoppingCart(['total' => ['totalQuantity' => 10]])
            ->setPaymentDay(0)->setPaymentFrequency(1)->setPaymentCount(12)->setPaymentShift(5)->send('paybox.send');

分期付款请求

与订阅计划相比，分期付款请求的设计用途略有不同。它允许您自由配置支付条款的日期和金额，最多为4次付款，而订阅的金额和日期是固定的。第一次付款总是即时处理。

分期付款请求的最基本示例代码可能如下所示

$severalTimesRequest = \App::make(\JulienMru\PayboxGateway\Requests\SeveralTimes::class);

return $severalTimesRequest->setCustomer([
                            'firstname' => 'John',
                            'lastname' => 'Doe',
                            'email' => 'john.doe@example.com',
                            'address' => 'Test Street',
                            'postcode' => '75015',
                            'city' => 'PARIS',
                            'countrycode' => 250 // ISO Numeric Code
                        ])
            ->setShoppingCart(['total' => ['totalQuantity' => 10]])
            ->setPayment1(20)
            ->setPayment2(Carbon\Carbon::now()->addDays(15), 25)
            ->setPayment3(Carbon\Carbon::now()->addDays(45), 30)
            ->setPayment4(Carbon\Carbon::now()->addDays(60), 40)
            ->send();

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

定义客户返回路由

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

处理事务验证路由

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

$payment = Payment::where('number', $request->input('order_number'))->firstOrFail();
$payboxVerify = \App::make(\JulienMru\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(\JulienMru\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，您应使用在处理“处理事务验证路由”步骤中收到的值，因此您可能需要在这一步保存它们以便在此处使用。

自定义商家名称

如果您想自定义PayBox支付表单上的商家名称，您可以在您的支付请求中使用setMerchantName函数。

警告：这不会更改客户银行对账单上显示的名称。

许可证

本软件包采用MIT许可证授权。