README

Larabanker - Laravel 的 Transbank

此包将非官方的 Transbank SDK 连接到您的 Laravel 应用程序中。

要求

PHP >= 8.0
Laravel 8.x

请检查旧版本以获取旧 Laravel 版本的安装。

安装

调用 composer 并将其添加到您的应用程序中。

composer require darkghosthunter/larabanker

文档

此包模拟了 Transbank SDK，因此您应该查看 Transbank 开发者网站上（西班牙语）的这些服务的文档。

快速入门

要开始使用 Transbank 服务，您可以使用包含的 Webpay、WebpayMall 和 Oneclick 门面以及 redirect() 方法，这些方法使用最少的参数并返回到 Transbank 的 GET 重定向。

use DarkGhostHunter\Larabanker\Facades\Webpay;

return Webpay::redirect('buy-order#1230', 1000);

或者，您仍然可以完全控制使用门面创建事务。

use DarkGhostHunter\Larabanker\Facades\Webpay;

$response = Webpay::create('buyOrder#1230', 1000, route('payment'));

return redirect()->away($response, 303);

从 API 1.2 开始，Transbank 服务支持 GET 重定向。不再需要使用带有 JavaScript 重定向的视图。

重定向使用默认路由名称进行，这集中了支付端点。

处理 POST 和会话销毁

Laravel 默认将 cookies 设置为 SameSite: lax。这意味着在支付失败或取消时，会话会被销毁。这是因为 Transbank 使用没有 cookies 的 POST 方法将您的应用程序重定向到您的应用程序，迫使 Laravel 重新创建一个空的新会话。

为了避免这种情况，您应该使用相同的路径从 Transbank 接收响应，但使用不同的控制器处理 GET 或 POST。Larabanker 方便地使用每个 Transbank 服务重定向点的路由名称，这些路由将在支付过程结束后被访问。

您可以在配置文件中更改这些路由名称。请确保为这些路由添加您的控制器以处理来自 Transbank 的传入响应。

在此示例中，我们将禁用 web 中间件以避免创建新的会话，并返回一个带有通用失败消息的视图。

use \DarkGhostHunter\Larabanker\Facades\Webpay;
use \Illuminate\Support\Facades\Route;

Route::get('transbank/webpay', function (Request $request) {
    $transaction = Webpay::commit($request->input('token_ws'));

    return view('payment.processed')->with('transaction', $transaction);
})->name('transbank.webpay');

Route::post('transaction/webpay, function (Request $request) {
    return view('payment.failed');
})->withoutMiddleware('web');

配置

虽然 Larabanker 设计得非常方便，无需设置太多，但您可以通过发布配置文件来深入了解

php artisan vendor:publish --provider="DarkGhostHunter\Larabanker\ServiceProvider"

您将收到包含以下内容的 larabanker.php 配置文件

<?php

return [
    'environment' => env('TRANSBANK_ENV', 'integration'),
    'credentials' => [
        // ...
    ],
    'redirects' => [
        'webpay'       => 'transbank.webpay',
        'webpayMall'   => 'transbank.webpayMall',
        'oneclickMall' => 'transbank.oneclickMall',
    ],
    'protect' => env('TRANSBANK_PROTECT', false),
    'cache' => null,
    'cache_prefix' => env('TRANSBANK_PROTECT_PREFIX', 'transbank|token')
];

不要担心，我们将逐一解释每个重要部分。

环境和凭证

<?php

return [
    'environment' => env('TRANSBANK_ENV', 'integration'),
    'credentials' => [
        'webpay' => [
            'key' => env('WEBPAY_KEY'),
            'secret' => env('WEBPAY_SECRET'),
        ],
        'webpayMall' => [
            'key' => env('WEBPAY_MALL_KEY'),
            'secret' => env('WEBPAY_MALL_SECRET'),
        ],
        'oneclickMall' => [
            'key' => env('ONECLICK_MALL_KEY'),
            'secret' => env('ONECLICK_MALL_SECRET'),
        ],
    ],
];

默认情况下，该包使用 integration 环境，这会进行模拟交易。

要使用 production 环境，这将进行所有实际交易，请将环境明确设置为 production

TRANSBANK_ENV=production

此外，您必须添加您的 Transbank 凭证，这些凭证将直接发放给您，用于您已签订的协议中的服务。您可以在 .env 文件中轻松完成此操作。

WEBPAY_KEY=5000000001
WEBPAY_SECRET=dKVhq1WGt_XapIYirTXNyUKoWTDFfxaEV63-O5jcsdw

重定向

<?php

return [
    'redirects_base' => env('APP_URL'),
    'redirects' => [
        'webpay'       => 'transbank.webpay',
        'webpayMall'   => 'transbank.webpayMall',
        'oneclickMall' => 'transbank.oneclickMall',
    ],
];

仅当使用 Webpay、WebpayMall 和 OneclickMall 门面时，您才能在创建事务时跳过发出 $returnUrl 或 $responseUrl 值，让 Larabanker 使用配置文件中发出的默认值。

use DarkGhostHunter\Larabanker\Facades\Webpay;

$response = Webpay::create('myOrder#16548', 1000);

端点保护

return [
    'protect' => env('TRANSBANK_PROTECT', false),
    'cache' => null,
    'cache_prefix' => env('TRANSBANK_PROTECT_PREFIX', 'transbank|token')
];

默认情况下禁用，此软件包提供暴力破解攻击防护中间件larabank.protect，用于返回URL。这些返回URL是您的应用程序端点，Transbank服务将通过GET或POST请求将用户重定向到这些端点。

如果禁用，中间件将不会验证令牌。

use \Illuminate\Support\Facades\Route;
use \App\Http\Controllers\WebpayController;

Route::post('/transbank/webpay', [WebpayController::class, 'receivePayment'])
     ->middleware('larabank.protect');

它使用缓存保存交易令牌5分钟，因此如果令牌不再有效，整个响应将被终止。您可以通过cache和cache_prefix分别更改缓存存储和前缀。

此功能适用于接收来自Webpay、Webpay Mall和Oneclick Mall服务的Transbank重定向。

许可证

此软件包是开源软件，许可协议为MIT。

Redcompra、Webpay、Onepay、Patpass和tbk是Transbank S.A.的商标。

此软件包不是由Transbank S.A.开发、批准、支持或认可的，也不是由Transbank S.A.直接或间接关联的自然人或公司。

darkghosthunter / larabanker

维护者

详情