To use this site please enable javascript on your browser! Integrate MPesa or Tigopesa on your Laravel Website Including Other Payment Gateways

Integrate MPesa or Tigopesa on your Laravel Website Including Other Payment Gateways

by Bryce Andy 01:02 Feb 02 '19

Pesapal Cover

For a long time it hasn't been easy to integrate mobile money payments with web applications as their APIs have been expensive and or difficult to use. The emergence of startups like Pesapal has made it easier to integrate using their simple API.

Using their PHP API, I created a Laravel package that could be easily used by Laravel developers.

Requirements & Installation

Before installing, make sure your project meets the following:

  • Laravel version 7.* and above
  • PHP version 7.4 and above
  • cURL extension for PHP must be installed on your server

Now you may install this package by running

composer require bryceandy/laravel_pesapal

Configuration

Next, we need to publish the configuration file that comes  with the package

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

After publishing, you will find a pesapal.php file in your config directory.

Head over to demo if you want a testing environment or live for a live integration and create a business account. You will obtain a API key and API secret for your integration.

Pesapal Register Page

Inside your .env file, create these environment variables and they will be used to set configuration values available in the published config/pesapal.php file

Use the keys you obtained from Pesapal to fill the key and secret. If you are on a live account, set the is_live variable to true.

PESAPAL_KEY=yourConsumerKey
PESAPAL_SECRET=yourConsumerSecret
PESAPAL_IS_LIVE=false
PESAPAL_CALLBACK_URL=

Thereafter, run the migration command as the package will load a database migration that stores the payment records

php artisan migrate

Usage

Before making a payment, setup a callback page.

Create a callback page and register its URL in the PESAPAL_CALLBACK_URL environment variable. This can be something like https://yourwebsite.com/callback

Once a payment process has been completed by the user, Pesapal will redirect to your site using the url.

Making a request to Pesapal for a payment.

Pesapal Payment Page

Pesapal requires a request sent to their API in order to display the payment page like the one above.

This package comes with a route /pesapal/iframe where you can post the data as follows:

/**
 * 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',
]

For the type field, leave the default as MERCHANT. If you use ORDER, be sure to read the Pesapal documentation first.

When the data is posted successfully, you will have a view of the form to make payments.

A new payment record will be recorded in your pesapal_payments table, now you can choose the payment option you prefer.

Fetching the payment status.

After making the payment you will be redirected to the callback URL as mentioned above, and Pesapal will redirect with two query parameters:

  • pesapal_merchant_reference – this is the same as $reference that you posted to Pesapal
  • pesapal_transaction_tracking_id - a unique id for the transaction on Pesapal that you can use to track the status of the transaction later

With these two we can now:

A. Use these parameters to query the payment status to display to the user.

Normally on your callback page you can display whatever you need to your customer to show that the payment is being processed.

But because Pesapal will send the payment tracking Id (which you have not recorded), you can save this unique tracking Id for your payment and also query for the payment status.

In the controller method where you display the callback page, query the status:

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)
    }
}

This way requires you to refresh the page because you may not know when the status has changed.

If this does not have a good user experience, you may setup an 'IPN listener' where Pesapal notifies you when a payment status has changed.

B. Setting up an IPN (Instant Payment Notifications) listener.

This only applies to merchant accounts. Create a route for your IPN listener, for example a GET request to /pesapal-ipn-listener

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

Your IPN Controller could look like this:

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.
        }
    }
}

This controller method will be called every time Pesapal sends you an IPN notification until the payment is completed or has failed.

Register IPN Settings

On your Pesapal dashboard find your Account Settings and click IPN Settings.

Fill in your website domain for example yourWebsite.com and IPN listener URL, for example yourWebsite.com/pesapal-ipn-listener.

This is important so that Pesapal can send IPN notifications.

Important

At this point you are ready to make payments, but in order for your business transactions to be official and live with Pesapal you need to contact them and inform them about your business.

10
2
Updated 08:07 Jul 09 '21

If you like this content, please consider buying me coffee.
Thank you for your support!

Become a Patron!

Join to participate in the discussion

icky testing Avatar icky testing 02:03 Mar 18 '23
Hello , can't get prompt on my phone when making payment
Kiwalabye45charles@gmail.com Charles Avatar Kiwalabye45charles@gmail.com Charles 04:01 Jan 09 '23
please i have a ready running application but i want to integrate in pesapal and am picking amout of payment from the database but now am confused for now where am i supposed to put my payment view
icky testing Avatar icky testing 03:12 Dec 03 '22
Hello Bryce. The iframe from PesaPal only returns TigoPesa for mobile payment. Is there something wrong?
2
Bryce Andy Avatar Bryce Andy 08:12 Dec 03 '22
If you are getting the iframe nothing has gone wrong, but if you are seeing TigoPesa only then it's something to do with PesaPal themselves
icky testing Avatar icky testing 02:03 Mar 18 '23
HELLO. C
Musumbi Denis Avatar Musumbi Denis 04:11 Nov 03 '22
Hello Bryce. Kindly share a piece of code of how you'll send the form details from your controller.
1
Bryce Andy Avatar Bryce Andy 06:11 Nov 07 '22
You can easily send this using your form, no need to create a controller for it: <form action="/pesapal/iframe" method="POST"> <input type="number" name="amount" /> ... </form>
1
Sharon Elly Avatar Sharon Elly 05:07 Jul 19 '22
Hi Bryce, thank you for this great tutorial, I keep facing this problem though when I send data to the pesapal/iframe route: Problem: parameter_absent | Advice: > oauth_parameters_absent | oauth_consumer_key&oauth_signature_method&oauth_signature&oauth_timestamp&oauth_nonce Any idea on what the solution is? I'll appreciate any help you can provide.
6
Bryce Andy Avatar Bryce Andy 06:07 Jul 19 '22
How are you sending your data?
Sharon Elly Avatar Sharon Elly 06:07 Jul 19 '22
By using postman, sending the data in json format, the result is always a blank page in preview format but when I check the source code the iframe link goes to demo.pesapal.com appended with all its parameters, and when I click that link is when I see the error
Bryce Andy Avatar Bryce Andy 08:07 Jul 19 '22
You can't test through Postman because the result is a redirection
Sharon Elly Avatar Sharon Elly 10:07 Jul 19 '22
i did a little work around of the result by saving it in an HTML document, that's how I could see the errors , so the live API works now, I have a new error on the demo side, it says: "Problem: consumer_key_unknown | Advice: > | " I'm using the Tanzanian test credentials to for the demo keys provided by https://developer.pesapal.com/api3-demo-keys.txt. I didn't see anywhere to register as a developer
Bryce Andy Avatar Bryce Andy 08:07 Jul 20 '22
From the error message it seems Pesapal doesn't recognize the test keys. Create a business account and use the keys obtained from that account
Sharon Elly Avatar Sharon Elly 11:07 Jul 20 '22
I had created a business account and got the credentials but they're live and I wanted a testing environment, I saw the instructions on their demo page I'll have to follow those. Thank you for the feedback!
1
Jere Mih Avatar Jere Mih 02:06 Jun 16 '19
does it work in kenya ..mpesa to mpesa
1
Bryce Andy Avatar Bryce Andy 12:06 Jun 19 '19
Yes it works
Elson Nyagwaru Avatar Elson Nyagwaru 03:04 Apr 20 '19
also, thank you for making this tutorial free to use and easy to use. god bless you
1
Bryce Andy Avatar Bryce Andy 10:04 Apr 25 '19
You are welcome, I am glad I could help!
Elson Nyagwaru Avatar Elson Nyagwaru 03:04 Apr 20 '19
second Mr Bryce what you are doing is so good, especially to Tanzania ICT. Its good to see tz developer make simple and easy library for another developer to use their skills and knowledge.
Elson Nyagwaru Avatar Elson Nyagwaru 03:04 Apr 20 '19
how to change from demo to live?
1
Bryce Andy Avatar Bryce Andy 10:04 Apr 25 '19
When you created a Pesapal account you used demo.pesapal.com but now you have to create another one using www.pesapal.com, and do not forget to change your new PESPAL_KEY & PESAPAL_SECRET values in .env
Elson Nyagwaru Avatar Elson Nyagwaru 07:04 Apr 20 '19
Sorry, an error occurred while processing your request. We are working to fix it as soon as we can. sory bro i get this error
1
Bryce Andy Avatar Bryce Andy 08:04 Apr 20 '19
Hi Elson, if you reached here it is a good sign that it works. Just change your account from demo to live