README

此包使 Laravel 开发者能够轻松使用 Pesapal API。

版本支持

安装

安装前要求

运行中的 Laravel 7.* 或更高版本
PHP 7.4 或更高版本
安装 cURL 扩展

现在运行

composer require bryceandy/laravel_pesapal

配置

接下来，我们发布包附带配置文件

php artisan vendor:publish --tag=pesapal-config

发布后，您将在您的 config 目录中找到一个 pesapal.php 文件

如果您想要测试环境，请访问 demo；如果您想要实时的集成，请访问 live 并创建一个企业账户。您将获得用于集成的密钥-密钥对

在您的 .env 文件中，创建以下环境变量，它们将用于设置在发布的 config/pesapal.php 文件中可用的配置值

使用从 Pesapal 获得的密钥填写密钥和密钥。如果您使用的是实时账户，请将 is_live 变量设置为 true。

PESAPAL_KEY=yourConsumerKey
PESAPAL_SECRET=yourConsumerSecret
PESAPAL_IS_LIVE=false
PESAPAL_CALLBACK_URL=

之后，运行迁移命令，因为包将加载一个存储支付记录的数据库迁移

php artisan migrate

使用方法

在执行支付之前，设置一个回调页面。

创建一个回调页面，并将其 URL 注册到 PESAPAL_CALLBACK_URL 环境变量中。例如 http://yourwebsite.com/callback

一旦用户完成支付过程，Pesapal 将使用此 URL 将用户重定向到您的网站。

向 Pesapal 发送支付请求。

Pesapal 需要发送一个请求到他们的 API，才能显示我们上面看到的表单。

此包包含一个路由 /pesapal/iframe，您可以按如下方式发送数据

/**
 * Create a form and send the appropriate values. You may as
 * well send url parameters where a view will be returned.
 */
[
    'amount' => 'Required, input should be numbers only',
    'currency' => 'Required, values can be TZS,KES,UGX or USD',
    'description' => 'Required, short description of the payment',
    'type' => 'Required, "MERCHANT" or "ORDER"',
    'reference' => 'Required, should be auto-generated and unique for every transaction',
    'first_name' => 'Optional',
    'last_name' => 'Optional',
    'email' => 'Required if there is no phone number',
    'phone_number' => 'Required if there is no email, include the country code. Example 255784999999',
]

type 字段，请保留默认值 MERCHANT。如果您使用 ORDER，请务必先阅读 Pesapal 文档。

数据成功发送后，您将看到用于进行支付的表单视图。

将在您的 pesapal_payments 表中记录一条新的支付记录，现在您可以选择您偏好的支付选项。

获取支付状态。

支付后，您将被重定向到上面提到的回调 URL，Pesapal 将使用两个查询参数进行重定向

pesapal_merchant_reference – 这与您发送给 Pesapal 的 $reference 相同
pesapal_transaction_tracking_id - 这是 Pesapal 交易的唯一 ID，您可以用它来跟踪交易状态

有了这两个参数，我们现在可以

A. 使用这些参数查询支付状态以显示给用户。

通常，在您的回调页面上，您可以显示任何您需要显示给客户的内容，以表明支付正在处理中。

但由于 Pesapal 将发送您尚未记录的支付跟踪 ID，因此您可以保存此唯一的跟踪 ID 用于您的支付，并查询支付状态。

在显示回调页面的控制器方法中，查询状态

namespace App\Http\Controllers;

use Bryceandy\Laravel_Pesapal\Facades\Pesapal;
use Bryceandy\Laravel_Pesapal\Payment;

class CallbackController extends Controller 
{
    public function index()
    {
        $transaction = Pesapal::getTransactionDetails(
            request('pesapal_merchant_reference'), request('pesapal_transaction_tracking_id')
        );
        
        // Store the paymentMethod, trackingId and status in the database
        Payment::modify($transaction);

        $status = $transaction['status'];
        // also $status = Pesapal::statusByTrackingIdAndMerchantRef(request('pesapal_merchant_reference'), request('pesapal_transaction_tracking_id'));
        // also $status = Pesapal::statusByMerchantRef(request('pesapal_merchant_reference'));

        return view('your_callback_view', compact('status')); // Display this status to the user. Values are (PENDING, COMPLETED, INVALID, or FAILED)
    }
}

这种方式需要你刷新页面，因为你可能不知道状态何时改变。

如果这不会提供良好的用户体验，你可以设置一个“IPN监听器”，当Pesapal通知你支付状态已改变时。

B. 设置IPN（即时支付通知）监听器。

这仅适用于商户账户。为你的IPN监听器创建一个路由，例如对/pesapal-ipn-listener的GET请求。

// For Laravel 7.*
Route::get('pesapal-ipn-listener', 'IpnController');
// For Laravel 8.* onwards
Route::get('pesapal-ipn-listener', \App\Http\Controllers\IpnController::class);

你的IPN控制器可能如下所示

namespace App\Http\Controllers;

use Bryceandy\Laravel_Pesapal\Facades\Pesapal;
use Bryceandy\Laravel_Pesapal\Payment;
use Illuminate\Support\Facades\Mail;

class IpnController extends Controller 
{
    public function __invoke()
    {
        $transaction = Pesapal::getTransactionDetails(
            request('pesapal_merchant_reference'), request('pesapal_transaction_tracking_id')
        );

        // Store the paymentMethod, trackingId and status in the database        
        Payment::modify($transaction);

        // If there was a status change and the status is not 'PENDING'
        if(request('pesapal_notification_type') == "CHANGE" && request('pesapal_transaction_tracking_id') != ''){

            //Here you can do multiple things to notify your user that the changed status of their payment
            // 1. Send an email or SMS (if your user doesnt have an email)to your user 
            $payment = Payment::whereReference(request('pesapal_merchant_reference'))->first();
            Mail::to($payment->email)->send(new PaymentProcessed(request('pesapal_transaction_tracking_id'), $transaction['status']));
            // PaymentProcessed is an example of a mailable email, it does not come with the package
        
            // 2. You may also create a Laravel Event & Listener to process a Notification to the user
            // 3. You can also create a Laravel Notification or dispatch a Laravel Job. Possibilities are endless! 

            // Finally output a response to Pesapal
            $response = 'pesapal_notification_type=' . request('pesapal_notification_type').
                    '&pesapal_transaction_tracking_id=' . request('pesapal_transaction_tracking_id').
                    '&pesapal_merchant_reference=' . request('pesapal_merchant_reference');
            
            ob_start();
            echo $response;
            ob_flush();
            exit; // This is mandatory. If you dont exit, Pesapal will not get your response.
        }
    }
}

此控制器方法将在每次Pesapal发送IPN通知时被调用，直到支付完成或失败。

重要

注册IPN设置

在你的Pesapal仪表板上找到“账户设置”，然后点击“IPN设置”。

填写你的网站域名，例如yourWebsite.com，以及IPN监听器URL，例如yourWebsite.co.tz/pesapal-ipn-listener。

这对于确保Pesapal能够发送IPN通知非常重要。

许可证

MIT许可证。

贡献者

此包基于Pesapal的PHP API。

BryceAndy > hello@bryceandy.com

赞助

如果你喜欢使用这个包，考虑向维护者做出贡献。

bryceandy / laravel_pesapal

维护者

详细信息