README

用于与 Flick 付款无缝工作的 Laravel 扩展包。

单一连接即可访问财务数据、身份、全球账户和多货币支付。在当地和全球范围内收集个人或企业的付款，并以多种货币结算，确保支付过程既经济又便捷。

此包还允许您接收来自 Flick 的所有类型钩子，它将验证并为您处理有效载荷。您可以在几分钟内开始收款。

Bank Transfers
Cards
Virtual Bank Accounts
Payouts

安装

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

composer require prevailexcel/laravel-flick

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

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

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

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

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

'providers' => [
    ...
    PrevailExcel\Flick\FlickServiceProvider::class,
    ...
]

此外，还需要注册 Facade，如下所示

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

配置

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

php artisan vendor:publish --provider="PrevailExcel\Flick\FlickServiceProvider"

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

<?php

return [
    
    /**
     * Public Key From FLICK Dashboard
     *
     */
    'secretKey' => getenv('FLICK_SECRET_KEY'),

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

    /**
     * FLICK Base URL
     *
     */
    'baseUrl' => env('FLICK_LIVE_URL', "https://flickopenapi.co"),

];

通用支付流程

尽管有多种支付订单的方法，但大多数支付网关都希望在您的结账过程中遵循以下流程

1. 客户被重定向到支付提供商的网站

在客户完成结账流程并准备支付后，客户必须被重定向到支付提供商的网站。

重定向是通过提交包含一些隐藏字段的表单来完成的。表单必须向支付提供商的网站发送 POST 请求。隐藏字段至少指定必须支付的金额、订单 ID 和哈希值。

哈希值是通过隐藏表单字段和一个非公开的秘密计算出来的。支付提供商使用此哈希值来验证请求是否有效。

2. 客户在支付提供商的网站上支付

客户到达支付提供商的网站，并可以选择支付方式。支付订单所需的全部步骤都由支付提供商负责。

3. 客户被重定向回您的网站

客户支付订单后，将被重定向回来。在重定向到商店网站的请求中，返回了一些值。这些值通常是订单 ID、支付结果和哈希值。

哈希值是根据返回的一些字段和一个非公开的秘密值计算出来的。此哈希值用于验证请求是否有效，并来自支付提供商。务必仔细检查此哈希值。

用法

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

FLICK_SECRET_KEY=sk_****_****************************************
FLICK_ENV=live

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

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

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

1. 开始支付
2. 设置回调 - Route::flick_callback。
3. 设置 webhook 并处理事件响应 - Route::flick_webhook。

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

让我们设置我们的控制器

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

use App\Http\Requests;
use App\Http\Controllers\Controller;
use Illuminate\Support\Facades\Redirect;
use PrevailExcel\Flick\Facades\Flick;

class PaymentController extends Controller
{

    /**
     * Redirect the User to Flick Payment Page
     * @return Url
     */
    public function redirectToGateway()
    {
        try{
            return Flick::getLink()->redirectNow();
        }catch(\Exception $e) {
            return Redirect::back()->withMessage(['msg'=> $e->getMessage(), 'type'=>'error']);
        }        
    }

    /**
     * Obtain Flick payment information
     * @return void
     */
    public function handleGatewayCallback()
    {
        $paymentDetails = flick()->getPaymentData();

        dd($paymentDetails);
        // Now you have the payment details,
        // you can store the reference ID in your db.
        // you can then redirect or do whatever you want
    }
}

/**
 *  In the case where you need to pass the data from your
 *  controller or via your client or app instead of a form
 *  
 */
 $data = [       
        'email' => "example@gmail.com",
        'Phoneno' => "08100000000",
        'amount' => "9000", // in naira
    ];

    // if monolithic, do
    return Flick::getLink($data)->redirectNow();

    // if API, do
    return Flick::getLink($data, true);

如果默认值不适用于您，您也可以自行设置其他详细信息。

 $data = [       
        'email' => "example@gmail.com",
        'Phoneno' => "08100000000",
        'amount' => "9000", // in naira

        'transactionId' => "Generate your own ID",
        'currency_collected' => "NGN", // USD, GBP, CAD
        'currency_settled' => 'NGN', // USD, GBP, CAD
    ];

现在用卡支付。

如果您已将用户卡信息以加密字符串的形式保存，您可以使用它来发起支付。

<?php

namespace App\Http\Controllers;

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

class PaymentController extends Controller
{  
    /**
     * You collect data from your blade form
     * and this returns the Account details for payment
     */
    public function createPayment()
    {
        try {
            // You can use the global helper flick()->method() or the Facade Flick::method().
           
           
            $card = "eZl0T7elDC3VWefiqYT4RujW7t...";

            return Flick::chargeCard($card);
            
        } catch (\Exception $e) {
            return redirect()->back()->withMessage(['msg' => $e->getMessage(), 'type' => 'error']);
        }
    }
}

用户将通过 PIN 或 OTP 完成支付。

处理 Webhook

您可以通过监听 webhook 并为用户提供服务。将重操作放在 handleWebhook() 方法中。此包将使用密钥哈希验证 webhook。

在您的控制器中

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

此包建议使用队列作业来处理 webhook 数据，尤其是当您处理如发送邮件等重操作时。

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

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

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

在 Laravel 11 中，您可以在 bootstrap/app.php 文件中这样做。

->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: [
        'flick/webhook', 
    ]);
})

将 'flick/webhook' 端点 URL 添加到 Flick 仪表板上的三个 webhook 字段；

Webhook URL : 127.0.0.1:8000/flick/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="Phoneno" 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-submit">
        <button class="btn btn-primary btn-block" type="submit"> Pay </button>
    </div>
</form>

当点击提交按钮时，客户会被重定向到支付页面。

因此现在客户在那里进行了一些操作（希望他们已经支付了订单），现在此包将客户重定向到回调 URL Route::flick_callback()。

我们必须验证重定向到我们网站的是否是一个有效的请求（我们不希望冒充者错误地放置未付款的订单）。

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

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

此包提供的其他一些流畅方法在此列出。

收集

/**
 * OTP verification
 *
 * @param string $otp
 * @param string $ref transaction ref or id.
 * @return array
 */
Flick::verifyOtp($otp, $ref);
// Or
flick()->verifyOtp($otp, $ref);

/**
 * PIN verification
 *
 * @param string $pin
 * @param string $ref transaction ref or id.
 * @return array
 */
Flick::verifyPin($pin, $ref);
// Or
flick()->verifyPin($pin, $ref);

/**
 * Get Info About Card
 */
Flick::lookupCard($card_first_six_digits);

账户

/**
 * Check your balance for the different currencies and categories available. Default is payouts.
 * 
 * @param null|string $category  Can be payouts, walletapi, or collections
 * @param null|string $currency  NGN, USD, GBP, or CAD. Default is NGN
 * @returns array
 */
Flick::checkBalance();

/**
 * Get Flick exchange rate. Either of the parameters must be NGN
 *
 * @param null|string $from  NGN, USD, GBP, or CAD. Default is NGN
 * @param null|string $to  NGN, USD, GBP, or CAD. Default is NGN
 *
 * @return array
 */
Flick::exchangeRate(?string $from = null, ?string $to = null);

/**
 * Generate transfer history statements with custom date ranges
 * @returns array
 */
Flick::transferHistory($data);

支付

/**
 * Move funds from your Flick balance to a bank account.
 * @returns array
 */
Flick::transfer($data = null);

工具

/**
 * Get all the bank codes for all existing banks in our operating countries.
 * @returns array
 */
Flick::banks();

/**
 * Verify the status of a transaction carried out on your Flick account
 * @returns array
 */
Flick::verifyTransaction(?string $ref = null);
// Or
request()->ref = "transactionId";
flick()->verifyTransaction();

/**
 * Resend webhook for a transaction.
 * @returns array
 */
Flick::resendWebhook(?string $ref = null);
// Or
request()->ref = "transactionId";
flick()->resendWebhook();

/**
 * Verify the status of a transfer carried out from your Flick account 
 * @returns array
 */
Flick::verifyTransfer(?string $ref = null);

/**
 * Verify the owner of a bank account using the bank code and the account uumber 
 * @returns array
 */
Flick::confirmAccount(?string $bank_code = null, ?string $account_number = null);

待办事项

• 添加 webhook 功能
• 添加全面的测试

贡献

请随意 fork 此包，并通过提交拉取请求以增强功能来贡献。

我如何感谢您？

为什么不 star github 仓库？我非常希望得到关注！为什么不分享此存储库的链接到 Twitter 或 HackerNews？传播消息！

谢谢！ Chimeremeze Prevail Ejimadu

许可证

MIT 许可证 (MIT)。请参阅 许可证文件 了解更多信息。