njoguamos / laravel-pesapal
A Laravel package for interacting with https://www.pesapal.com api
Fund package maintenance!
njoguamos
Installs: 1 487
Dependents: 0
Suggesters: 0
Security: 0
Stars: 3
Watchers: 1
Forks: 1
Open Issues: 3
Requires
- php: ^8.1 | ^8.2 | ^8.3
- illuminate/contracts: ^10.0 | ^11.0
- saloonphp/saloon: ^3.7.0
- spatie/laravel-data: ^4.4
- spatie/laravel-package-tools: ^1.16
Requires (Dev)
- larastan/larastan: ^2.9
- laravel/pint: ^1.14
- nunomaduro/collision: ^v7.10 | ^v8.1
- orchestra/testbench: ^8.22 | ^9.0
- pestphp/pest: ^2.34
- pestphp/pest-plugin-arch: ^2.7
- pestphp/pest-plugin-laravel: ^2.3
- phpstan/extension-installer: ^1.3
- phpstan/phpstan-deprecation-rules: ^1.1
- phpstan/phpstan-phpunit: ^1.3
- dev-main
- v1.2.32
- v1.2.31
- v1.2.30
- v1.2.28
- v1.2.26
- v1.2.22
- v1.1.20
- v1.1.14
- v1.1.11
- v1.1.7
- v1.1.3
- v1.1.0
- v1.0.26
- v1.0.22
- v1.0.18
- v1.0.13
- v1.0.10
- v1.0.7
- v1.0.2
- v1.0.1
- v1.0.0
- v1.0-beta.5
- v1.0-beta.4
- v1.0-beta.3
- v1.0-beta.2
- v1.0-beta.1
- v0.0.5
- v0.0.4
- v0.0.3
- v0.0.2
- v0.0.1
- dev-dependabot/composer/laravel/framework-11.31.0
- dev-remove-dev-instructions
This package is auto-updated.
Last update: 2024-11-12 22:59:41 UTC
README
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:
composer require njoguamos/laravel-pesapal
This packages comes with the following tables
pesapal_tokens
- to store theaccess_token
andexpires_at
for the Pesapal APIpesapal_ipns
- to store the Instant Payment Notifications
Publish and run the migrations
php artisan vendor:publish --tag="pesapal-migrations"
php artisan migrate
You can optionally publish the config file
php artisan vendor:publish --tag="pesapal-config"
Update your environment variables in your application.
PESAPAL_LIVE= PESAPAL_CONSUMER_KEY= PESAPAL_CONSUMER_SECRET=
Usage
1. Generate access_token
To generate an access_token
you can run the following command:
php artisan pesapal:auth
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.
# Laravel 10 -> app/Console/Kernel.php use NjoguAmos\Pesapal\Models\PesapalToken; class Kernel extends ConsoleKernel { protected function schedule(Schedule $schedule): void { # Other scheduled commands $schedule->command('pesapal:auth')->everyFourMinutes(); Schedule::command('model:prune', ['--model' => [PesapalToken::class]])->everyFiveMinutes(); } }
# Laravel 11 -> routes/console.php use Illuminate\Support\Facades\Schedule; use NjoguAmos\Pesapal\Models\PesapalToken; Schedule::command('pesapal:auth')->everyFourMinutes(); Schedule::command('model:prune', ['--model' => [PesapalToken::class]])->everyFiveMinutes();
You can also call the createToken' in
Pesapalclass directly to generate the
access_token. The method will return null or an new
PesapalToken` instance.
use NjoguAmos\Pesapal\Pesapal; $token = Pesapal::createToken();
The results of createToken
is an instance of PesapalToken
Eloquent Model. Which mean you can call Eloquent methods e.g.
$data = $token->toArray();
[ 'access_token' => "eyJhbGciOiJIUzI1NiIs...6pVj1_DS37ghMGQ", 'expires_at' => Carbon\Carbon instance ]
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 anaccess_token
that is not expired.
use NjoguAmos\Pesapal\Pesapal; $ipn = Pesapal::createIpn( url: 'https://www.yourapp.com/ipn', ipnType: IpnType::GET, );
The results of createIpn
is an instance of PesapalIpn
Eloquent Model. Which mean you can call Eloquent methods e.g.
$data = $ipn->toArray();
[ 'url' => 'https://www.yourapp.com/ipn' 'ipn_id' => 'e32182ca-0983-4fa0-91bc-c3bb813ba750' 'type' => 'GET' 'status' => 'Active' ]
info The url should be a public url that can be accessed by pesapal.com. The
ipnType
can be eitherIpnType::GET
orIpnType::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 anaccess_token
that is not expired. Of course, if you scheduled thepesapal:auth
command, you should not worry about theaccess_token
being expired.
3. Get Registered IPNs Endpoint
There are two ways to get the registered IPNs.
- You can use the
getIpns
method in thePesapal
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.
use NjoguAmos\Pesapal\Pesapal; use NjoguAmos\Pesapal\Pesapal; $response = Pesapal::getIpns();
Sample successful response
[ [ "url" => "https://www.myapplication.com/ipn", "created_date" => "2022-03-03T17:29:03.7208266Z", "ipn_id" => "e32182ca-0983-4fa0-91bc-c3bb813ba750", "error" => null, "status" => "200" ], [ "url"=> "https://ipn.myapplication.com/application2", "created_date"=> "2021-12-05T04:23:45.5509243Z", "ipn_id"=> "c3bb813ba750-0983-4fa0-91bc-e32182ca", "error"=> null, "status"=> "200" ] ]
- or get the IPNs from the database.
use NjoguAmos\Pesapal\Models\PesapalIpn; $ips = PesapalIpn::all();
[ [ "id" => 1 "url" => "http://kautzer.com/omnis-ut-qui-illo-id-laborum-numquam" "ipn_id" => "767e3275-d504-41a0-920a-dd752aafb5ac" "type" => 0 "status" => 1 "created_at" => "2024-03-18T08:10:32.000000Z" "updated_at" => "2024-03-18T05:10:32.000000Z" ], [ "id" => 2 "url" => "http://www.cole.org/qui-fugiat-accusamus-molestiae-aspernatur-sequi-eum-non-quae.html" "ipn_id" => "de07604f-c06b-4ccf-9cb5-dd75aaaff99f" "type" => 0 "status" => 1 "created_at" => "2024-03-18T08:10:33.000000Z" "updated_at" => "2024-03-18T05:10:33.000000Z" ] ]
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
.
use NjoguAmos\Pesapal\Enums\ISOCurrencyCode; use NjoguAmos\Pesapal\Enums\ISOCountryCode; use NjoguAmos\Pesapal\Enums\RedirectMode; use NjoguAmos\Pesapal\Pesapal; use NjoguAmos\Pesapal\DTOs\PesapalOrderData; use NjoguAmos\Pesapal\DTOs\PesapalAddressData; $ipnId = PesapalIpn::latest()->first()->ipn_id; $orderData = new PesapalOrderData( id: fake()->uuid(), currency: ISOCurrencyCode::KES, amount: fake()->randomFloat(nbMaxDecimals: 2, min: 50, max: 500), description: 'Test order', callbackUrl: fake()->url(), notificationId: $ipnId, cancellationUrl: fake()->url(), redirectMode: RedirectMode::PARENT_WINDOW, ); // All fields are optional except either phoneNumber or emailAddress $billingAddress = new PesapalAddressData( phoneNumber: '0700325008', emailAddress: 'test@xample.com', countryCode: ISOCountryCode::KE firstName: 'Amos', middleName: 'Njogu' // lastName: '' line2: "Gil House, Nairobi, Tom Mboya Street", // city: "", // state: "", // postalCode: "", // zipCode: "", ); $order = Pesapal::createOrder( orderData: $orderData, billingAddress: $billingAddress, );
Sample successful response
[ "order_tracking_id" => "b945e4af-80a5-4ec1-8706-e03f8332fb04", "merchant_reference" => "TEST1515111119", "redirect_url" => "https://cybqa.pesapal.com/pesapaliframe/PesapalIframe3/Index/?OrderTrackingId=b945e4af-80a5-4ec1-8706-e03f8332fb04", "error" => null, "status" => "200" ]
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.
use NjoguAmos\Pesapal\Pesapal; $transaction = Pesapal::getTransactionStatus( orderTrackingId: 'b945e4af-80a5-4ec1-8706-e03f8332fb04', ); // $transaction either an array or an instance of Saloon Response
Sample successful response
[ "payment_method" => "MpesaKE" "amount" => 6.0 "created_date" => "2024-03-19T20:08:46.39" "confirmation_code" => "SCJ8JQ26SW" "order_tracking_id" => "af2234da-03ee-4b60-b2dd-dd746bcda1bd" "payment_status_description" => "Completed" "description" => null "message" => "Request processed successfully" "payment_account" => "2547xxx56689" "call_back_url" => "http://127.0.0.1:8000/pesapal-callback?OrderTrackingId=af2234da-03ee-4b60-b2dd-dd746bcda1bd&OrderMerchantReference=1" "status_code" => 1 "merchant_reference" => "1" "payment_status_code" => "" "currency" => "KES" "error" => [ "error_type" => null "code" => null "message" => null ] "status" => "200" ]
6. Recurring / Subscription Based Payments
- TODO: Add documentation for recurring payments
7. Refund Request
- TODO: Add documentation for refund request
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.
use NjoguAmos\Pesapal\Pesapal; $transaction = Pesapal::getTransactionStatus( orderTrackingId: 'b945e4af-80a5-4ec1-8706-e03f8332fb04', ); if (is_array($transaction)) { // The API call was successful and response is an array // [ // "payment_method" => "MpesaKE" // "amount" => 6.0 // "created_date" => "2024-03-19T20:08:46.39" // "confirmation_code" => "SCJ8JQ26SW" // "....more field" // ] } else { // The API call was not successful. The response is an instance of Saloon Response // $transaction->status() ---> response status code. // $transaction->headers() ---> Returns all response headers // $transaction->getPendingRequest() ---> PendingRequest class that was built up for the request. }
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 deletingtests/Fixtures
and running the tests.
composer test
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
License
The MIT License (MIT). Please see License File for more information.