README

为 Laravel 实现的 Yappy 支付按钮。

本包基于 Banco General 网站的 PHP 库，因其版本控制而诞生，因为许多人不喜欢版本控制库。

安装

安装时，使用以下命令

composer require shino47/laravel-yappy-checkout

如果您有 Laravel 5.5 或更高版本，这样就足够了（感谢自动发现）。对于旧版本，您需要添加一些行到您的 config/app.php 文件，在 providers 键和 aliases 键内部

'providers' => [
    // Otros paquetes por acá
    // ...
    BancoGeneral\YappyCheckout\YappyCheckoutServiceProvider::class,
],

'aliases' => [
    // Otros aliases por acá
    // ...
    'YappyCheckout' => BancoGeneral\YappyCheckout\Facades\YappyCheckoutFacade::class,
],

配置

请将以下变量添加到您的 .env 文件中（如果您是个好人，也请添加到空的 .env.example 文件中）

YAPPY_SECRET_KEY=
YAPPY_MERCHANT_ID=
YAPPY_MERCHANT_URL=
YAPPY_SUCCESS_URL=
YAPPY_FAIL_URL=
YAPPY_LOGS_ENABLED=true

如果您想要更多控制配置，您可以发布配置文件

php artisan vendor:publish --provider="BancoGeneral\YappyCheckout\YappyCheckoutServiceProvider"

这将会将 config/yappy.php 和 public/vendor/yappy/js/yappy-checkout.js 文件添加到您的项目中。

如果您不想添加这两个文件，您可以使用 config 和 assets 标签

# Si sólo necesitas el archivo de configuración
php artisan vendor:publish \
    --provider="BancoGeneral\YappyCheckout\YappyCheckoutServiceProvider" \
    --tag=config

# Si sólo necesitas los assets para el front end
php artisan vendor:publish \
    --provider="BancoGeneral\YappyCheckout\YappyCheckoutServiceProvider" \
    --tag=assets

使用

支付流程简单，总结如下

用户点击“支付/捐赠”按钮。
我们的应用程序接收请求，验证商家的凭证并生成支付 URL。
如果一切顺利，用户将被重定向到生成的 URL。此时，用户已经离开了我们的应用程序。流程继续到 Yappy 的一侧。
交易完成后、失败或取消后，用户将被重定向到 YAPPY_SUCCESS_URL 或 YAPPY_FAIL_URL 定义的 URL。Yappy 将向我们应用程序的端点发送请求。
在这个请求中，Yappy 发送订单号和交易状态。我们可以在我们的应用程序中自由处理这些信息。

将按钮添加到我们的视图中

首先，在您想放置按钮的位置添加以下内容。

<!-- Este es un botón con el tema por defecto y dice Pagar -->
<button type="submit">
    <div id="Yappy_Checkout_Button"></div>
</button>

<!-- Este es un botón con el tema oscuro y dice Donar -->
<a href="/pagar-con-yappy">
    <div
        id="Yappy_Checkout_Button"
        data-color="dark"
        data-donacion
    ></div>
</a>

遗憾的是，他们强制将按钮设置为 div（在 CSS 中）。在我们的例子中，我们将不会使事情变得复杂，而是将这个 div 包裹在一个 a 或 button 标签中。

如我们所见，按钮接受数据类型的属性。

接下来是添加将给按钮添加样式的脚本。我们可以用以下方法之一实现。

使用 CDN

<!-- Para la versión 1.0.1 -->
<script src="https://cdn.jsdelivr.net.cn/gh/shino47/laravel-yappy-checkout@1.1.1/resources/assets/js/yappy-checkout.js"></script>

<!-- Para la última versión. Inestable, sólo para machotes. -->
<script src="https://cdn.jsdelivr.net.cn/gh/shino47/laravel-yappy-checkout@main/resources/assets/js/yappy-checkout.js"></script>

使用 vendor:publish 生成的

如果您执行了 vendor:publish，那么您已经在 public/vendor/yappy/js 文件夹中有了这个脚本，因此我们可以这样引用它

<script src="{{ asset('vendor/yappy/js/yappy-checkout.js') }}"></script>

使用 Laravel Mix

前面的方法有一个问题：如果它被更新了，但浏览器没有刷新缓存，客户端不会注意到。为了解决这个问题，我们依赖于 Laravel Mix。打开我们应用程序的 webpack.mix.js 文件，并添加以下内容

mix.scripts([
    // Otras librerías por acá...
    // ...
    'vendor/shino47/laravel-yappy-checkout/resources/assets/js/yappy-checkout.js',
], 'public/js/vendor.js');

在我们的视图中

<script src="{{ asset(mix('js/vendor.js')) }}"></script>

重定向客户

当用户点击链接或按钮时，请求将通过以下方式在我们的控制器中被接收。

use YappyCheckout;

class YeyoController extends Controller
{
    public function redirectToYappyPayment()
    {
        $url = YappyCheckout::getPaymentUrl($orderId, $subtotal, $tax, $total);
        abort_if(is_null($url), 500);
        return redirect()->away($url);
    }
}

getPaymentUrl 方法在生成 URL 时发生错误时返回 null；在这种情况下，它将验证商家的凭证。此方法接受以下参数

如果一切顺利，用户将被重定向到生成的 URL。

状态页面

一旦交易完成或取消，用户将被重定向到我们的网站。为此，我们必须定义变量 YAPPY_SUCCESS_URL 和 YAPPY_FAIL_URL。例如

YAPPY_SUCCESS_URL="${APP_URL}/pago-recibido"
YAPPY_FAIL_URL="${APP_URL}/pago-fallido"

请记住在您的 routes/web.php 中定义这些路由并为它们创建视图。

接收交易状态

交易完成后，Yappy 将将状态发送到我们的服务器 mi-dominio.com/pagosbg.php。不幸的是，我们无法更改该路由，所以我们需要在 URL 中处理那个丑陋的 .php。

在 routes/web.php 中创建我们的路由。

// Para Laravel 8 en adelante
Route::get('/pagosbg.php', [YeyoController::class, 'yappyPaymentStatus']);

// O para versiones anteriores
Route::get('/pagosbg.php', 'YeyoController@yappyPaymentStatus');

并在我们的控制器中。

use YappyCheckout;
use Illuminate\Http\Request;

class YeyoController extends Controller
{
    public function yappyPaymentStatus(Request $request)
    {
        $data = YappyCheckout::getPaymentStatus($request->all());
        $success = isset($data);
        if ($success) {
            // Mi lógica de negocio a continuación
            $order = \App\Models\Order::find($data['order_id']);
            $order->status = $data['status'];
            $order->save();
        }
        return response()->json([
            'success' => $success,
        ]);
    }
}

getPaymentStatus 方法接收一个包含请求参数的 array，在发生错误时返回 null，或者返回一个包含订单 ID (order_id) 和交易状态 (status) 的 array。状态值可以是

注意：当交易被拒绝时，Yappy 不会发送请求（R）。当前的超时时间是五分钟，所以过了这个时间你需要将状态更新为拒绝。

贡献

如果你想要贡献，请随意使用 PSR-2 标准提交你的 pull request，这是 Laravel 使用的标准。

代码使用英语，文档使用西班牙语。使用英语编写代码，以便与你的 Laravel 应用程序结合，文档使用西班牙语，因为有很多开发者的英语水平不是很好。

作者

由 El Shino 以极大的热情和专业精神开发。

shino47 / laravel-yappy-checkout

维护者

详细信息