Download the PHP package njoguamos/laravel-pesapal without Composer

Laravel 10+ package for interacting with Pesapal API

This package provides a way of interacting with Pesapal API. It provides a way of generating access_token and storing Instant Payment Notifications (IPNs) in the database. It also provides a way of submitting order requests and checking the status of a transaction.

Why use this package

• To provide a way of generating Pesapal api access_token which normally expires after 5 minutes
• Offer a gateway to interacting with Pesapal v3 API
• Provide a way of storing Instant Payment Notifications (IPNs) in the database
• Saves you time from writing the same code over and over again

Playground

If you are looking to test this package, I have created a playground where you can test the package without having to create a new Laravel project.

Installation

You can install the package via composer:

This packages comes with the following tables

• pesapal_tokens - to store the access_token and expires_at for the Pesapal API
• pesapal_ipns - to store the Instant Payment Notifications

Publish and run the migrations

You can optionally publish the config file

Update your environment variables in your application.

Usage

1. Generate access_token

To generate an access_token you can run the following command:

The command will get a fresh access_token from Pesapal API using the CONSUMER_KEY and CONSUMER_SECRET and save it in the database. The access_token is valid for 5 minutes therefore is wise to schedule the command to run every 4 minutes. In addition, when you have set model:prune command, all expired access_token will be deleted from the database since they are no longer useful.

You can also call the createToken' inPesapalclass directly to generate theaccess_token. The method will return null or an newPesapalToken` instance.

`

The results of createToken is an instance of PesapalToken Eloquent Model. Which mean you can call Eloquent methods e.g.

2. Create Instant Payment Notification

To create an instant payment notification, you can use the createIpn method in the Pesapal class. The method will return an instance of PesapalIpn or null if the request fails.

info Ensure that that your pesapal_tokens table as an access_token that is not expired.

`

The results of createIpn is an instance of PesapalIpn Eloquent Model. Which mean you can call Eloquent methods e.g.

info The url should be a public url that can be accessed by pesapal.com. The ipnType can be either IpnType::GET or IpnType::POST.

You can go ahead and use the ipn_id to submit a Submit Order Requests.

info Ensure that that your pesapal_tokens table as an access_token that is not expired. Of course, if you scheduled the pesapal:auth command, you should not worry about the access_token being expired.

3. Get Registered IPNs Endpoint

There are two ways to get the registered IPNs.

1. You can use the getIpns method in the Pesapal class to get a IPN from Pesapal API. This method returns an array for successful response or an instance of Saloon Response for failed response.

Sample successful response

2. or get the IPNs from the database.

4. Submit Order Request Endpoint

To submit an order request, you can use the createOrder method in the Pesapal class. You will need to construct a DTO for PesapalOrderData and PesapalAddressData as shown below. This method returns an array for successful response or an instance of Saloon Response for failed response.

info You must provide a registered PesapalIpn.

Sample successful response

You can now re-direct the user to the redirect_url to complete the payment.

5. Get Transaction Status Endpoint

You can check the status of a transaction using OrderTrackingId issued when creating an order. You can do so by using the getTransactionStatus method in the Pesapal class. This method returns an array for successful response or an instance of Saloon Response for failed response.

Sample successful response

6. Recurring / Subscription Based Payments

• [ ] TODO: Add documentation for recurring payments

7. Refund Request

• [ ] TODO: Add documentation for refund request

8. Retrying Requests

If for some reason, the payment did not complete and you have the order tracking ID, you can retry the payment by redirecting the user to the Pesapal payment page.

A note about responses

For flexibility and simplicity, the Pesapal static method returns an array for successful responses or an instance of Saloon Response for failed responses.

Example, when getting the transaction status using getTransactionStatus will either return an array of transaction details or an instance of Saloon Response if the request was not successful.

You can learn more about the [Saloon Response(https://docs.saloon.dev/the-basics/responses). You can use the response to diagnose the issue with the request.

Testing

Info Where possible, the tests uses real sandbox credentials, and as such the request is not mocked. The resulting response is saved at tests/Fixtures and used in future tests. Where it is impossible to use real credentials, the request is mocked. You can recreate the fixtures by deleting tests/Fixtures and running the tests.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Njogu Amos
• All Contributors

License

The MIT License (MIT). Please see License File for more information.