README

一个用于无缝处理 Bani 支付的 Laravel 扩展包。

此包还允许您接收来自 Bani 的 webhooks，它将为您验证并处理有效载荷。它还实现了 Bani Pop 支付小部件并处理了 laravel 的回调。您可以在几分钟内开始收集法定货币和加密货币支付。

安装

PHP 5.4+ 或 HHVM 3.3+，以及 Composer 是必需的。

要获取 Laravel Bani 的最新版本，只需要求它

composer require prevailexcel/laravel-bani

或者将以下行添加到您的 composer.json 文件的 require 块中。

"prevailexcel/laravel-bani": "1.0.*"

然后您需要运行 composer install 或 composer update 以下载它并更新自动加载器。

安装 Laravel Bani 后，您需要注册服务提供者。打开 config/app.php 并将以下内容添加到 providers 键中。

如果您使用 Laravel >= 5.5，您可以跳过此步骤，并转到 配置

'providers' => [
    ...
    PrevailExcel\Bani\BaniServiceProvider::class,
    ...
]

同样，您可以注册 Facade，如下所示

'aliases' => [
    ...
    'Bani' => PrevailExcel\Bani\Facades\Bani::class,
    ...
]

配置

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

php artisan vendor:publish --provider="PrevailExcel\Bani\BaniServiceProvider"

一个名为 bani.php 的配置文件，其中包含一些合理的默认值，将被放置在您的 config 目录中

<?php

return [

    /**
     * Tribe Account Ref Key From Bani Dashboard
     *
     */
    'tribeAccountRef' => getenv('BANI_TRIBE_ACCOUNT_REF'),

    /**
     * Public Key From Bani Dashboard
     *
     */
    'publicKey' => getenv('BANI_PUBLIC_KEY'),

    /**
     * Merchant Key From Bani Dashboard
     *
     */
    'merchantKey' => getenv('BANI_PRIVATE_KEY'),

    /**
     * Merchant Key From Bani Dashboard
     *
     */
    'accessToken' => getenv('BANI_ACCESS_TOKEN'),

    /**
     * You enviroment can either be live or stage.
     * Make sure to add the appropriate API key after changing the enviroment in .env
     *
     */
    'env' => env('BANI_ENV', 'stage'),

    /**
     * BANI Live URL
     *
     */
    'liveUrl' => env('BANI_LIVE_URL', "https://live.getbani.com/api/v1"),

    /**
     * BANI Stage URL
     *
     */
    'stageUrl' => env('BANI_STAGE_URL', "https://stage.getbani.com/api/v1"),
];

一般支付流程

这是支付流程应有的样子

1. 收集客户订单数据

您必须收集用户支付内容的信息和金额。这些通常包括电子邮件、金额、电话号码、名字和姓氏。您可以直接从您的 blade 表单（如果您正在构建一个网站）或通过请求从客户端应用程序中这样做。

2. 获取 Bani Pop 小部件或调用您想要的方法。

Bani 允许用户在离开您的网站或应用程序之前完成支付。因此，您可以调用 payWithWidget() 获取 Bani Pop 小部件，并让用户完成支付。

如果您想实现自己的 UI 或您正在构建一个 API，您可以使用各种流畅的方法来开始和完成支付。您可以使用 bankTransfer()、mobileMoney()、payWithCrypto()、startPayWithOpay() 等更多方法。

3. 支付后为您提供服务

完成支付后，您必须确认支付。此包可以帮助轻松处理 webhook。如果您使用 pop 小部件，它还可以帮助您处理回调。

建议使用 webhook 响应，该响应由本包为您验证，然后标记订单为已支付，并将他们发送到感谢页面，发送电子邮件，或执行您想要执行的操作。

用法

打开您的 .env 文件并添加所有必要的键，如下所示

BANI_TRIBE_ACCOUNT_REF=**-**************************
BANI_PUBLIC_KEY=***_****_*********************
BANI_PRIVATE_KEY=**********************
BANI_ACCESS_TOKEN=****************************************************
BANI_ENV=stage

如果您使用的是像 heroku 这样的托管服务，请确保将上述详细信息添加到您的配置变量中。 请记住，当您处于生产状态时，将 BANI_ENV 更改为 'live' 并更新密钥。

接下来，您必须设置您的路由。

您应该有 3 个路由来开始。

1. 开始支付
2. 设置回调（如果您想使用 payWithWidget()）- Route::callback。
3. 设置 webhook 并处理事件响应 - Route::webhook。

// Laravel 5.1.17 and above
Route::post('/pay', 'PaymentController@createPayment')->name('pay');
Route::callback(PaymentController::class, 'handleGatewayCallback');
Route::webhook(WebhookController::class, 'handleWebhook');

或者

// Laravel 8 & 9
Route::post('/pay', [PaymentController::class, 'createPayment'])->name('pay');
Route::callback(PaymentController::class, 'handleGatewayCallback');
Route::webhook(WebhookController::class, 'handleWebhook');

现在使用小部件支付。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use PrevailExcel\Bani\Facades\Bani;

class PaymentController extends Controller
{  
    /**
     * You collect data from your blade form
     * and this returns the Bani Pop Widget
     */
    public function createPayment()
    {
        try {
            return Bani::payWithwidget();
        } catch (\Exception $e) {
            return redirect()->back()->withMessage(['msg' => $e->getMessage(), 'type' => 'error']);
        }
    }
    
    public function handleGatewayCallback()
    {
        // verify transaction and get data
        $data = bani()->getPaymentData();

        // Do anything you want
        dd($data);
    }
}

这会打开小部件，并让用户完成支付。该程序将重定向到 handleGatewayCallback()，该函数验证支付，然后您可以使用支付数据。

要测试银行转账，选择银行后，复制账户信息，前往 https://demo-checkout.getbani.com/test_bank/ 进行测试支付，然后返回您的网站并点击“我已经支付 {金额}”按钮。

现在使用银行转账支付。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use PrevailExcel\Bani\Facades\Bani;

class PaymentController extends Controller
{  
    /**
     * You collect data from your blade form
     * and this returns the Account details for payment
     */
    public function createPayment()
    {
        try {
                $data = [
                    "pay_amount" => 10000,
                    "holder_account_type" => "temporary",
                    "customer_ref" => "MC-69941173958782368244",
                    "custom_data" => ["id" => 1, "color" => "white"],
                ];
                
                // You can use the global helper bani()>method() or the Facade Bani:: method().
                return bani()->bankTransfer($data);
        } catch (\Exception $e) {
            return redirect()->back()->withMessage(['msg' => $e->getMessage(), 'type' => 'error']);
        }
    }

    public function handleWebhook()
    {
        // verify webhook and get data
        bani()->getWebhookData()->proccessData(function ($data) {
            // Do something with $data
            logger($data);
            // If you have heavy operations, dispatch your queued jobs for them here
            // OrderJob::dispatch($data);
        });
        
        // Acknowledge you received the response
        return http_response_code(200);
    }
}

要获取客户引用，您可以通过创建带有用户详情的 bani()->createCustomer($userdata) 方法或通过电话 bani()->customer("+2348011111111") 查找用户来获取用户详情。

这将返回包含账户详情的数据，您可以将这些数据显示或发送给用户以进行支付。您可以监听webhook并服务用户。将重操作写入 handleWebhook() 方法中。

该软件包建议使用队列作业处理webhook数据，特别是如果您处理像发送邮件这样的重操作。

webhook路由 Route::webhook(Controller::class, 'methodName') 是如何工作的？

在幕后，默认情况下，这将注册一个POST路由 'bani/webhook' 到您提供的控制器和方法。因为发送webhook的应用程序没有获取csrf-token的方式，您必须将该路由添加到 VerifyCsrfToken中间件的except数组中。

protected $except = [
    'bani/webhook',
];

一个示例表单看起来是这样的

<form method="POST" action="{{ route('pay') }}">
    @csrf
    <div class="form-group" style="margin-bottom: 10px;">
        <label for="phone-number">Phone Number</label>
        <input class="form-control" type="tel" name="phone" required />
    </div>
    <div class="form-group" style="margin-bottom: 10px;">
        <label for="email">Email</label>
        <input class="form-control" type="email" name="email" required />
    </div>
    <div class="form-group" style="margin-bottom: 10px;">
        <label for="amount">Amount</label>
        <input class="form-control" type="number" name="amount" required />
    </div>
    <div class="form-group" style="margin-bottom: 10px;">
        <label for="first-name">First Name</label>
        <input class="form-control" type="text" name="firstName" />
    </div>
    <div class="form-group" style="margin-bottom: 10px;">
        <label for="last-name">Last Name</label>
        <input class="form-control" type="text" name="lastName" />
    </div>
    <div class="form-submit">
        <button class="btn btn-primary btn-block" type="submit"> Pay </button>
    </div>
</form>

当点击提交按钮时，客户将被重定向到弹出小部件。

所以现在客户在那里执行了一些操作（希望他或她已经支付了订单），现在该软件包将客户重定向到回调URL Route::callback()。

我们必须验证重定向到我们网站的请求是否有效（我们不想冒名顶替者错误地放置未支付订单）。

在处理来自支付提供者的请求的控制器中，我们有

Bani::getPaymentData() - 此函数调用 verifyTransaction() 方法并确保它是有效的交易，否则抛出异常。

此软件包提供的某些流畅方法在此列出。

客户

// For all methods, you can get data from request()

/**
 * Check if the customer already exist
 * @returns array
 */
Bani::customer(?string $phone, ?string $ref);
// Or
request()->phone;
bani()->customer();


/**
 * Create a customer object
 * @returns array
 */
Bani::createCustomer();
// Or
bani()->createCustomer();


/**
 * Update a customer object
 * @returns array
 */
Bani::updateCustomer();
// Or
bani()->updateCustomer();


/**
 * Fetch your customer delivery/billing address(es).
 */
Bani::listBillingAddress();
// Or
bani()->listBillingAddress();


/**
 * Add customer delivery/billing address(es)
 * @returns array
 */
Bani::addBillingAddress();
// Or
bani()->addBillingAddress();


/**
 * Uupdate customer's delivery/billing address
 * @returns array
 */
Bani::updateBillingAddress();
// Or
bani()->updateBillingAddress();


/**
 * Delete customer's delivery/billing address
 * @returns array
 */
Bani::deleteBillingAddress();
// Or
bani()->deleteBillingAddress();

收集支付

/**
 * Accept payments from customers via bank transfer
 * @returns array
 */
Bani::bankTransfer();

/**
 * Accept payments via mobile money from customers
 * @returns array
 */
Bani::mobileMoney();

/**
 * Accept payments from customers via crypto and get settled in fiat
 * @returns array
 */
Bani::payWithCrypto();

/**
 * generate a deposit address to accept strictly DLT payments 
 * and get settled with the same currency
 */
Bani::getWalletAddress();

/**
 * Accept one-click payment from customers via bani shopper wallet
 * @returns array
 */
Bani::startPayWithBaniShopper();

/**
 * Complete 2nd step in payment from customers via bani shopper wallet
 * @returns array
 */
Bani::completePayWithBaniShopper();

验证

/**
 * The fastest and most secure way to verify mobile numbers using USSD instead of SMS OTPs.
 * @returns array
 */
Bani::verifyPhone(?string $phone);

/**
 * This endpoint is used to confirmed if the customer phone number has been verified
 * @returns array
 */
Bani::checkUssdStatus(?string $verification_reference);

杂项

/**
 * This endpoint can be used to carry out a lookup on customer account
 * @returns array
 */
Bani::confirmEwallet($wallet, $tag, ?string $type);

待办事项

• 添加全面测试
• 添加对代理端点的支持
• 添加对更多杂项端点的支持
• 添加对账单支付端点的支持
• 添加对支付端点的支持

贡献

请随意fork此软件包，通过提交拉取请求来贡献以提高功能。

如何感谢你？

为什么不给github存储库加星？我渴望关注！为什么不分享这个存储库的链接到Twitter或HackerNews？传播消息！

别忘了在 Twitter上关注我！也请在 LinkedIn上关注我！

还可以查看我在medium上的页面，了解关于Laravel的文章和教程 在medium上关注我！

谢谢！Chimeremeze Prevail Ejimadu。

许可证

MIT许可证（MIT）。有关更多信息，请参阅 许可证文件。