README

Laravel应用程序的Pesapal V3包

此包可让您在5分钟内设置Pesapal V3网络支付

预安装要求

Laravel 8*
PHP 7.4或更高版本
CURL已安装

安装

composer require nyawach/laravel-pesapal

配置

要发布pesapal配置文件和迁移，请运行

php artisan vendor:publish --provider="Nyawach\LaravelPesapal\PesaPalServiceProvider"

示例配置文件

//Please specify the environment pesapal is running on: production or sandbox

'pesapal_env'=>env('PESAPAL_ENV'),


/*
 * The application consumer key
 *
 */
'consumer_key'=>env('PESAPAL_CONSUMER_KEY'),

/*
 * The application consumer Secret
 */

'consumer_secret'=>env('PESAPAL_CONSUMER_SECRET'),

/*
 * It is a good practise to guard your routes. We will use
 * unique string to guard our callback and IPN Urls. Provide a random string to
 * to guard the endpoints
 */

'pesapal_guard'=>env('PESAPAL_GUARD'),

/*
 * After registering the IPN URL(s). Pesapal provides an IPN ID.
 * Copy that ID and save in you .env file. For a transaction to go through
 * it must have an ipn_id
 */


'pesapal_ipn_id'=>env('PESAPAL_IPN_ID')

请参考config/pesapal.php并在您的.env文件中创建环境变量。以下是一个示例。

PESAPAL_ENV=production
PESAPAL_CONSUMER_KEY="Yourconsumer key"
PESAPAL_CONSUMER_SECRET="Your secret key"
PESAPAL_GUARD="Random string"
PESAPAL_IPN_ID="IPN Id from Pesapal"

PEASAPAL_ENV：请指定环境是沙盒还是生产环境 PESAPAL_CONSUMER_KEY和PESAPAL_CONSUMER_SECRET生产密钥可以在这里获取。沙盒或测试密钥可以在这里找到 PESAPAL_GUARD：保护您的回调和通知URL是一个好习惯。想一个独特的字符串并将其设置为您的保护。这是URL的示例：https://www.myapplication/callback/ahd55hrg57edhWYDGSS

PESAPAL_IPN_ID：对于生产环境，请使用此表单创建IPN URL并保存ID。对于测试或沙盒环境，请使用此表单。IPN URL可以是POST或GET，选择您更舒适的一种。

IPN代表即时支付通知。当针对交易进行支付时，Pesapal将触发一个IPN调用到与该交易相关的通知URL。此通知URL通常位于您的服务器上。这些通知允许您在交易状态发生变化时实时接收警报。

IPN尤其重要，因为它允许您在以下情况下接收通知

由于互联网问题，您的客户在支付后断开连接
您的客户遇到服务器错误，因此Pesapal和您的应用程序在回调URL加载之前断开连接。
您的客户在支付过程中退出您的应用程序/关闭浏览器。
交易被拒绝。

或者注册IPN URL

在您的控制器中

use Nyawach\LaravelPesapal\Facades\LaravelPesapal;
class PesapalController extends Controller
    {

    public function registerIpn(){
    $postData=array();
    //Sample Notification URL guarded by unique string
     $postData["url"]='https://mywebsite/getNotification/'.config('pesapal.pesapal_guard');
 
    /* IPN Notification type. 
    * This will tell Pesapal how to send the notification. As a POST or GET request
    */
    $postData["ipn_notification_type"]='POST';
 
    return LaravelPesapal::registerIpn($postData);
 
    }
}

请确保您已在.env文件中保存IPN ID。

成功的IPN注册响应看起来像这样。

提交订单请求

Pesapal的工作方式是提交订单请求。成功的订单将返回包含order_tracking_id和Iframe链接的响应。您可以在您的网站上渲染支付iframe或将用户重定向到iframe链接进行支付。之后，您可以提交请求以获取支付状态。

保存订单详情到您的数据库也很重要。

下面是如何提交订单请求的示例

use Nyawach\LaravelPesapal\Facades\LaravelPesapal;
use Nyawach\LaravelPesapal\Models\Pesapal;

class PesapalController extends Controller
{
//submit an order request
 public function submitOrder(){
 $postData = array();
        $postData["language"] = "EN"; //nullable
        $postData["currency"] = "KES"; //This represents the currency you want to charge your customers. ISO formats
        $postData["amount"] = number_format(1,2); //must be float value and required
        $postData["id"] = 234; //Can be your unique order or product id and is required
        $postData["description"] = "Payment for order number AFED67"; //required
        $postData["billing_address"]["phone_number"] = "07XXXXXXXX";//client phone number required if email unavailable
        $postData["billing_address"]["email_address"] = "john.doe@example.com"; //client email address
        $postData["billing_address"]["country_code"] = "KE";//2 characters long country code in [ISO 3166-1]
        $postData["billing_address"]["first_name"] = "John";
        $postData["billing_address"]["middle_name"] = "Doe";
        $postData["billing_address"]["last_name"] = "Musa";
        $postData["billing_address"]["line_1"] = "";//nullable
        $postData["billing_address"]["line_2"] = "";
        $postData["billing_address"]["city"] = "Nairobi";//nullable
        $postData["billing_address"]["state"] = "Kenya";//nullable
        $postData["billing_address"]["postal_code"] = "";//nullable
        $postData["billing_address"]["zip_code"] = "";//nullable
        $postData["callback_url"] = "https://www.myapplication.com/response-page/".config('pesapal.pesapal_guard');//ensure you guard your callback url
        $postData["notification_id"] = config('pesapal.pesapal_ipn_id'); //IPN_id from your .env file
        $postData["terms_and_conditions_id"] = "";
        //return $postData;
        $order=LaravelPesapal::getMerchantOrderURL($postData);
         
         /*
          * Save the transaction details to the database then later update
          * based on transaction status
          * Then render the iframe to present the user with a payment
          * interface
        
       */
       
       $transaction=new Pesapal();
       $transaction->tracking_id=$order->order_tracking_id;
       $transaction->language=$postData['language'];
       $transaction->currency=$postData['currency'];
       $transaction->amount=$postData['amount'];
       $transaction->merchant_reference=$postData['id'];
       $transaction->description=$postData["description"];
       $transaction->phone_number=$postData["billing_address"]["phone_number"] ; 
       $transaction->email=$postData["billing_address"]["email_address"];
       $transaction->country_code=$postData["billing_address"]["country_code"];
       $transaction->first_name=$postData["billing_address"]["first_name"];
       $transaction->middle_name=$postData["billing_address"]["middle_name"];
       $transaction->last_name=$postData["billing_address"]["last_name"];
       $transaction->billing_address_line_1=$postData["billing_address"]["line_1"];
       $transaction->billing_address_line_2=$postData["billing_address"]["line_2"];
       $transaction->city=$postData["billing_address"]["city"];
       $transaction->state=$postData["billing_address"]["state"];
       $transaction->postal_code=$postData["billing_address"]["postal_code"];
       $transaction->zip_code=$postData["billing_address"]["zip_code"];
       
       $transaction->save();
       
     //You only need to save fields that are important to you
     
     return $order;
       
       
 }

         
         
}

在成功提交订单请求后，您将得到一个看起来像这样的响应

redirect_url包含iframe链接。将客户端重定向到该链接以完成支付或将它渲染在您的网站上。以下是如何渲染它的示例

<!--some page content here-->
<div>
    <iframe src="https://pay.pesapal.com/iframe/PesapalIframe3/Index/?OrderTrackingId=483decd1-cf2a-4ce4-8475-df6c07da6a51" height="100%" width="100%" title="Payment Iframe"></iframe>
</div>
<!--other page content here-->

这是支付iframe渲染后的样子

获取交易状态

一旦Pesapal将客户重定向到您的回调URL并触发您的IPN URL，您需要使用OrderTrackingId检查支付状态。

交易状态返回交易信息和状态代码。这将允许您根据状态代码更新交易详情。状态代码如下

0 - 无效
1 - 完成
2 - 失败
3 - 已撤销

以下是如何请求交易状态的示例

use Nyawach\LaravelPesapal\Facades\LaravelPesapal;
use \Nyawach\LaravelPesapal\Models\Pesapal;

class PesapalController extends Controller{

//callback url function

public  function pesapalCallback(Request $request){
   $transaction_status=LaravelPesapal::getTransactionStatus($request->OrderTrackingId)
   /*
    * Based on the transaction status_code you can update the transaction details as
    * failed  or complete. If the transaction is not complete
    * you can redirect the users to attempt the payment again.
    */
    
    //if the transaction is complete
    
    if ($transaction_status->status_code===1){
    $order=Pesapal::where('tracking_id',$request->OrderTrackingId)->firstOrFail();
     //check if the amounts match
     if ($order->amount==$transaction_status->amount){
      $order->status=$transaction_status->status_code
      $order->payment_method=$transaction_status->payment_method
      $order->save()
      //redirect user to another page. Maybe thank you page
     }else{
     // do something else if the amounts do not match
     }
    }else{
     //do something else such redirecting users to attempt the payment again
    }
}

}

成功的获取交易状态应返回类似于以下响应。

退款支付

使用此端点向客户退款。以下为示例

use Nyawach\LaravelPesapal\Facades\LaravelPesapal;
class PesapalController{

    public function refundPayments(){
        /*
         * confirmation_code:This refers to payment confirmation code that was returned by the processor
         * amount: Amount to be refunded.
         * username: Identity of the user who has initiated the refund.
         * remarks: A brief description on the reason for the refund.
         */
        $postData=array();   
        $postData['confirmation_code']='AA11BB22' //required
        $postData['amount']='100.00'//required
        $postData['username']='John Doe', //required
        $postData['remarks'] //required
        
       return LaravelPesapal::refundTransaction($postData)
        
  
    }

}

在请求成功的情况下，将返回以下响应

退款API使用确认码进行识别。确保您存储所有在获取交易状态端点返回的支付确认码非常重要。

安全和漏洞

如果您在laravel-pesapal中发现安全漏洞，请通过nyawach41@gmail.com向Joshua Nyawach发送电子邮件。所有安全漏洞都将得到及时解决。

许可证

Laravel-pesapal是一个开源软件，根据MIT许可证授权。

nyawach / laravel-pesapal

维护者

详细信息