README

此包将Pesapal v3 API与Laravel集成。目前仅限于Pesapal电子商务API，尽管未来计划也添加POS API。该包包含测试用例，以确保包具有一定的可靠性和可预测性。

要求

1. PHP >= 8.1
2. Laravel 10或更高版本
3. Pesapal账户

安装

要安装此包，我们需要使用composer要求它。

    composer require otim-otim/pesapal-laravel-integration

配置

此时，需要将包的配置文件发布到主项目中。因此，我们运行以下命令：

    php artisan vendor:publish --provider="OtimOtim\PesapalIntegrationPackage\PesapalIntegrationPackageServiceProvider" --tag="config"

这将把PesapalIntegrationPackage.php文件添加到您主项目的config文件夹中。此文件的內容如下：

<?php

return [
  "CONSUMER_KEY" => "", // enter your consumer key here

  "CONSUMER_SECRET" => "", //enter your consumer secret here

  'SAND_BOX_URL' => 'https://cybqa.pesapal.com/pesapalv3/api', //enter sandbox url here
  'LIVE_URL'  => 'https://pay.pesapal.com/v3/api', //enter live url here


  /*
  get the notification id from pesapal
  and add here.
  check pesapal documentation for more details
  */
  'NOTIFICATION_ID' => '', //notification id from pesapal
  /*
  url pesapal will hit this route whenever action is done to a payment request
  NB:be sure to create this route
  for our case, this will be a post route
  */
  'NOTIFICATION_URL' => '', 

  /*
  url pesapal will redirect your user to after processing payment 
  NB:be sure to create this route
  */
  'CALLBACK_URL' => '', 
  /*
  url pesapal will redirect your user to after canceling payment 
  NB:be sure to create this route, if you want to enable payemnt request cancelation.
  check pesapal documentation for more details
  */
  'CANCELLATION_URL' => '', 


];

此时，设置您的通知URL路由（该路由接收POST请求）非常重要。

接下来，我们需要从pesapal通过以下URL获取通知ID：

获取pesapal沙箱通知ID

获取pesapal实时账户通知ID

虽然取消URL是可选的，但其余属性需要提供值。回调URL是默认值，但可以通过将回调URL请求值传递给请求对象来切换到您应用程序的首选值。（稍后详细介绍）。

现在我们准备运行我们的迁移。

php artisan migrate

用法

要使用此包，我们只需将包类导入到我们需要访问其功能的文件中，如下所示：

use OtimOtim\PesapalIntegrationPackage\Facades\Pesapal;

1. 准备订单请求

为了准备订单请求，我们需要使用PaymentRequestDTO dto类发送数据，这还需要在文件的顶部导入。

use OtimOtim\PesapalIntegrationPackage\Http\DTO\PaymentRequestDTO;

支付请求构造函数期望在传入的数组中具有以下值：

 $data = [
            'id' => '657-dfetr-iuy', //a uuid is prefered, but you can use your unique string to identify the transaction from your merchant side.
            "amount" => 2000,
            "currency" => 'UGX',// use standard currency code
            "description" => 'making a payment',
            "reference" => Uuid::uuid4()->toString(),
            'call_back_url' => route('payment.show', $payment), //this is optional, and can be set in case you want to overide the default CALLBACK_URL from the config file above. 
            'billing_address' => [ // atleast email address or phone_number should be provided. Otherwise validation will fail.
                'email_address' => $user->email,
                'phone_number' => $user->phone_number,
                'first_name' => $user->first_name,
                'middle_name' => $user->middle_name,
                'last_name' => $user->last_name,
            ]

        ];

        $dto = new PaymentRequestDTO($data);

1. 开始支付

有了我们的数据传输对象（dto），我们现在可以开始使用paypal进行支付。

$pay_url = Pesapal::initiatePayment($dto, $user, $item);

initiatePayemnt方法接受3个参数：

1. 包含请求处理数据的dto。
2. 此支付应附加的用户。它应该是一个Laravel模型。
3. 我们为其支付的项目模型。

如果成功，此方法返回一个重定向URL，将用户带到pesapal界面，以完成交易。

1. 检查交易状态

您可以使用getTransactionDetails()方法在任何时候检查交易状态。

$transaction = Pesapal::getTransactionDetails($merchant_reference);

$merchant_reference是您分配给上面id数组值的商家参考。

1. 更新数据库中的交易详情

您可以通过调用updateTransactionStatus()来更新您自己的数据库中的交易状态。

$transaction = Pesapal::updateTransactionStatus($merchant_reference);

1. 取消支付请求

只有未完成的支付才能取消。您可以通过调用cancelPaymentRequest()方法来完成此操作。

$transaction = cancelPaymentRequest($order_tracking_id)

其中：- order_tracking_id：由pesapal提供的唯一订单跟踪ID。如果成功，它将返回一个交易模型，否则将抛出错误。因此，请确保捕获它。

当您通过配置文件中设置的notification url路由收到pesapal的通知时，您通常可以利用上述步骤3和4。

下一步

很明显，该软件包仍在开发中，因为撤销交易和设置定期付款的工作仍在进行中。我希望在下一个版本中也能添加POS api。

本项目采用MIT许可，所以请不要害怕进行分支开发，提交PR，或指出任何问题或改进点。

如果您使用了这个软件包，也请别忘了留下评论或评价。我会非常感激。