abdallhsamy/laravel-hyperpay

MENA 地区的 Hyperpay 支付网关的 Laravel 包。

v0.1.2 2021-05-09 17:17 UTC

README

StyleCI Shield Latest Version on Packagist Total Downloads

Laravel HyperPay 提供了一种简单的方式来处理不同状态的所有交易。

安装

您可以通过 composer 安装此包

composer require abdallhsamy/laravel-hyperpay

数据库迁移

Laravel-hyperpay 提供了一个迁移来处理其自己的交易,安装后别忘了运行迁移

php artisan migrate

如果您想进行更新或更改迁移的路径,可以使用 vendor:publish 命令发布它

php artisan vendor:publish --tag="hyperpay-migrations"

此迁移有一个名为 Transaction 的模型,如果您的应用程序使用 多租户,您可以根据 hyperpay transaction 模型创建一个新的交易模型。

use Hyn\Tenancy\Traits\UsesTenantConnection;
use Abdallhsamy\LaravelHyperpay\Models\Transaction as ModelsTransaction;

class Transaction extends ModelsTransaction
{
    use UsesTenantConnection;
}

然后别忘了更新配置文件 app/hyperpay.php 中的 transaction_model 路径

<?php

return [
    //
    "transaction_model" => 'YOUR_NEW_TRANSACTION_MODEL_NAMESPACE',
    //
];

设置和配置

您还可以使用以下命令发布配置文件

php artisan vendor:publish --tag="hyperpay-config"

之后您可以在 app/hyperpay.php 中看到该文件

在开始使用 Laravel-hyperpay 之前,将 ManageUserTransaction 特性添加到您的用户模型中,此特性提供了多项任务,使您能够从给定的用户执行交易过程。

use Abdallhsamy\LaravelHyperpay\Traits\ManageUserTransactions;

class User extends Authenticatable
{
    use ManageUserTransactions;
}

此包使用用户模型,将是 App\UserApp\Models\User,否则您可以在 .env 中定义您的用户模型

PAYMENT_MODEL=App\Models\User

HyperPay 密钥

接下来,您应该在应用程序的 .env 中配置您的 Hyperpay 环境

SANDBOX_MODE=true
ACCESS_TOKEN=
ENTITY_ID_MADA=
ENTITY_ID=
# default SAR
CURRENCY=

创建交易

要使用此包在 Hyperpay 中创建交易,我们需要准备结账然后生成表单。

准备结账

use Abdallhsamy\LaravelHyperpay\Facades\LaravelHyperpay;

class PaymentController extends  Controller
{
    public function prepareCheckout(Request $request)
    {
        $trackable = [
            'product_id'=> 'bc842310-371f-49d1-b479-ad4b387f6630',
            'product_type' => 't-shirt'
        ];
        $user = User::first();
        $amount = 10;
        $brand = 'VISA' // MASTER OR MADA

        return LaravelHyperpay::checkout($trackable_data, $user, $amount, $brand, $request);
    }
}

您也可以通过使用以下命令创建账单类将账单数据附加到结账中,所有账单文件您都可以在 app/Billing 文件夹中找到。

php artisan make:billing HyperPayBilling

然后使用

use Abdallhsamy\LaravelHyperpay\Facades\LaravelHyperpay;
use App\Billing\HyperPayBilling

LaravelHyperpay::addBilling(new HyperPayBilling())->checkout($trackable_data, $user, $amount, $brand, $request);

您还可以通过使用 addMerchantTransactionId($id) 生成自己的 merchantTransactionId 并告诉包使用它

use Illuminate\Support\Str;

$id = Str::random('64');

LaravelHyperpay::addMerchantTransactionId($id)->addBilling(new HyperPayBilling())->checkout($trackable_data, $user, $amount, $brand, $request);

接下来,prepareCheckout 操作返回的响应

{
    "buildNumber": "",
    "id": "RANDOME_ID.uat01-vm-tx04",
    "message": "successfully created checkout",
    "ndc": "RANDOME_ID.uat01-vm-tx04",
    "result": {
        "code": "000.200.100",
        "description": "successfully created checkout"
    },
    "script_url": "https://test.oppwa.com/v1/paymentWidgets.js?checkoutId=RANDOME_ID.uat01-vm-tx04",
    "shopperResultUrl": "shopperResultUrl",
    "status": "200",
    "timestamp": "2021-04-05 11:16:50+0000"
}

要创建支付表单,您只需将以下 HTML/JavaScript 代码行添加到您的页面中。

<script src="{{ script_url }}"></script>
<form
    action="{{shopperResultUrl}}"
    class="paymentWidgets"
    data-brands="VISA MASTER"
></form>

支付状态

交易过程完成后,Hyperpay 会将用户重定向到商家页面,使用您可以在配置文件 app/hyperpay.php 中配置的 shopperResultUrl,通过更新 redirect_url 的值。

// app/hyperpay.php

return [
    //
    "redirect_url" => "/hyperpay/finalize",
    //
]

您还可以通过使用 addRedirectUrl($url) 动态添加 redirect_url,如果需要添加动态 URL,例如使用多租户或在重定向 URL 中添加一些参数,则可以覆盖默认配置 redirect_url

$redirect_url = $req->headers->get('origin'). '/finalize';

LaravelHyperpay::addRedirectUrl($redirect_url)->addBilling(new HyperPayBilling())->checkout($trackable_data, $user, $amount, $brand, $request);

重定向后,您可以使用一个操作来处理最终步骤

use Abdallhsamy\LaravelHyperpay\Facades\LaravelHyperpay;

class PaymentController extends Controller
{
    public function paymentStatus(Request $request)
    {
        $resourcePath = $request->get('resourcePath');
        $checkout_id = $request->get('id');
        return LaravelHyperpay::paymentStatus($resourcePath, $checkout_id);
    }
}

事件处理器

Laravel-hyperpay 在交易过程中提供了两个事件,在最终确定后,此包会触发成功交易

每个事件都包含 trackable_datahyperpay_data,这些数据用于准备结账

监听器示例

首先,我们使用以下命令创建一个新的监听器

php artisan make:listener TransactionSuccessListener

然后转到 app/Providers/EventServiceProvider 并将事件与您的监听器注册

class EventServiceProvider extends ServiceProvider
{
    /**
     * The event listener mappings for the application.
     *
     * @var array
     */
    protected $listen = [
        Registered::class => [
            SendEmailVerificationNotification::class,
        ],
         'Abdallhsamy\LaravelHyperpay\Events\SuccessTransaction' => [
            'App\Listeners\TransactionSuccessListener',
        ],
    ];

    //
}

在每次成功交易中,laravel-hyperpay 包会触发一个包含必要数据的带有事件,请参阅我们的 TransactionSuccessListener 类。

<?php

namespace App\Listeners;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Support\Facades\Log;

class TransactionSuccessListener
{
    /**
     * Create the event listener.
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    /**
     * Handle the event.
     *
     * @param  object  $event
     * @return void
     */
    public function handle($event)
    {
       $hyperpay_data =  $event->transaction['hyperpay_data'];

       $trackable_data =  $event->transaction['trackable_data'];
    }
}

您也可以使用 Abdallhsamy\LaravelHyperpay\Events\FailTransaction 事件做同样的事情。

测试

composer test

变更日志

请参阅 CHANGELOG 了解最近更改的详细信息。

贡献

请参阅CONTRIBUTING以获取详细信息。

安全

如果您发现任何与安全相关的问题,请发送电子邮件至abdallhsamy2011@gmail.com,而不是使用问题跟踪器。

致谢

许可证

MIT许可证(MIT)。请参阅许可证文件以获取更多信息。

Laravel hyperpay 模板

您可以使用此存储库来检查laravel-hyperpay-boilerplate包的集成。