README

PHP 用于 Webpay、Webpay Mall 和 Oneclick Mall 的简单易用的 Transbank SDK。

use Laragear\Transbank\Facades\Webpay;
use Laragear\Transbank\Http\Requests\WebpayRequest;

public function pay(Request $request)
{
    return Webpay::create('pink teddy bear', 1990, url('confirm'));
}

public function confirm(WebpayRequest $payment)
{
    if ($payment->isSuccessful()) {
        return 'Your pink teddy bear is on the way!';
    };
}

注意

目前仅支持 Webpay。Webpay Mall 和 Oneclick Mall 将基于支持计划。

成为赞助商

您的支持使我能够保持此包免费、更新和可维护。或者，您也可以 传播信息！

要求

Laravel 10 或更高版本

安装

您可以通过 Composer 安装此包

composer require laragear/transbank

用法

此 SDK 模拟了来自官方 Transbank SDK for PHP 的所有 Webpay 方法。

您可以在 Transbank 开发者网站上查看这些服务的文档。

Webpay

快速入门

使用您想要进行支付的服务的服务外观。

例如，要创建支付请求，使用 Webpay::create()，并附带支付完成后返回您应用的 URL。

use Laragear\Transbank\Facades\Webpay;

public function pay(Request $request)
{
    return Webpay::create('pink teddy bear', 1990, route('confirm'));
}

完成后，您可以使用控制器中的方便的 WebpayRequest 来确认支付。

use Laragear\Transbank\Http\Requests\WebpayRequest;

public function confirm(WebpayRequest $request)
{
    $transaction = $request->transaction();
    
    if ($transaction->isSuccessful()) {
        return 'Your pink teddy bear is on the way!';
    };
}

环境和凭据

默认情况下，此 SDK 在集成环境中启动，其中所有交易都通过使用 Transbank 自己的集成服务器进行模拟，并提供集成凭据。

Transbank 将为您的每个签约服务提供生产凭据。您可以使用 .env 文件方便地设置它们。

WEBPAY_KEY=597055555532
WEBPAY_SECRET=579B532A7440BB0C9079DED94D31EA1615BACEB56610332264630D42D0A36B1C

要在生产模式下操作，其中所有交易都是真实的，您需要在您的 .env 环境文件中将环境显式设置为 production。

TRANSBANK_ENV=production

注意

生产密钥在集成环境中不起作用，反之亦然。

中间件端点保护

您可能想要使用包含的 transbank.protect 中间件来验证来自 Transbank 的交易响应（Transbank 返回用户的路由）。它将取消任何没有正确令牌的请求。

use Illuminate\Support\Facades\Route;

Route::get('confirm', function (WebpayRequest $request) {
    // ...
})->middleware('transbank.handle')

此外，您还可以启用端点保护，仅允许 Transbank 请求进入应用程序。

交易失败中间件

对于交易的 Transbank 失败响应是通过 POST 请求发送的。这会 破坏会话，因为这些没有 cookies 返回，因此会生成一个新的空会话。这使得身份验证变得无用，并丢失引用或预期的 URL。

为了避免这种情况，请使用方便的 RouteRedirect 外观创建一个处理 POST 失败请求回您的应用程序的现成路由。当此重定向被处理时，您的浏览器会将 cookies 发送到应用程序，恢复会话。

use Illuminate\Support\Facades\Route;
use Laragear\Transbank\Http\Requests\WebpayRequest;
use Laragear\Transbank\Facades\RouteRedirect;

Route::get('confirm', function (WebpayRequest $request) {
    // ...
})->middleware('transbank.protect');

RouteRedirect::as('confirm');

默认情况下，重定向使用相同的路径，但您可以使用第二个参数进行更改。

use Illuminate\Support\Facades\Route;
use Laragear\Transbank\Http\Requests\WebpayRequest;
use Laragear\Transbank\Facades\RouteRedirect;

Route::get('confirm', function (WebpayRequest $request) {
    // ... Handle the successful transaction.
})->middleware('transbank.protect');

Route::get('failed-transaction', function () {
    // ... Handle the failed transaction.
})->middleware('transbank.protect');

RouteRedirect::as('confirm', 'failed-transaction');

重要

如果您使用您自己的中间件来验证 CSRF/XSRF 令牌，请将类设置为 RouteRedirect::$csrfMiddleware。

事件

您将能够听到所有开始和完成的交易。此包发送以下事件

TransactionCreating 在创建 Transbank 中的交易之前。
TransactionCreated 在 Transbank 中创建交易但待支付后。
在Transbank完成交易或退款后，无论成功与否，都会调用TransactionCompleted。

异常

所有异常都实现了TransbankException，因此您可以轻松捕获并检查发生了什么。

重要

银行或信用卡发行者正确拒绝的交易不会抛出异常。

存在4种类型的异常

ClientException：任何由不良交易、配置错误、中断、放弃、超时或无效值引起的错误。
ServerException：任何Transbank内部服务器错误。
NetworkException：来自Transbank服务器的任何通信错误，如网络超时或错误的端点。
UnknownException：任何其他错误。

高级配置

如果您需要精细调整，可以使用方便的配置文件。使用Artisan发布它。

php artisan vendor:publish --provider="Laragear\Transbank\TransbankServiceProvider" --tag="config"

您将收到包含以下内容的config/transbank.php文件：

<?php

return [
    'environment' => env('TRANSBANK_ENV'),
    'http' => [
        'timeout' => 10,
        'retries' => 3,
        'options' => [
            'synchronous' => true
        ]
    ],
    'credentials' => [
        // ...
    ],
    'protect' => [
        'enabled' => false,
        'store' => env('TRANSBANK_PROTECT_CACHE'),
        'prefix' => 'transbank|token',
    ],
]

环境

return [
    'environment' => env('TRANSBANK_ENV'),
]

要在生产环境中使用此包，您必须明确使用production启用它。为此，使用您的.env文件。

TRANSBANK_ENV=production

这将指示该包使用生产服务器进行Transbank服务。您应该将其与您的生产凭证结合使用。

HTTP客户端

return [
    'http' => [
        'timeout' => 10,
        'retries' => 3,
        'options' => [
            'synchronous' => true
        ]
    ],
]

此数组处理对Transbank的每个请求的等待时间、重试次数以及其他传递给底层Guzzle HTTP客户端的原始选项。

凭证

return [
    'credentials' => [
        // ...
    ],
]

此数组包含每个服务的凭证（密钥 & 密钥）对。此包已预置集成凭证，因此您可以直接开始开发和测试。

端点保护

return [
    'protect' => [
        'enabled' => false,
        'store' => env('TRANSBANK_PROTECT_CACHE'),
        'prefix' => 'transbank|token',
    ],
]

默认禁用，您可以使用transbank.protect中间件进一步保护您的端点。一旦启用，它将保存每个创建的交易令牌5分钟，一旦Transbank返回带有令牌的用户，如果请求不是由令牌生成的或已过期，则终止请求。

此功能还处理要使用的缓存存储以及将令牌存储到缓存时使用的前缀。

许可证

此特定包版本根据发布时的MIT许可证条款进行许可。

Redcompra、Webpay、Oneclick、Onepay、Patpass和Transbank是Transbank S.A.的商标。本包及其作者与Transbank S.A.无关。

laragear / transbank

维护者

详细信息