Welcome, Guest

Troubleshooting IPN / Status update failures
(1 viewing) (1) Guest
Official Pesapal announcements are conveyed through this forum
  • Page:
  • 1

TOPIC: Troubleshooting IPN / Status update failures

Troubleshooting IPN / Status update failures 2 years, 3 months ago #2327

  • lazro
  • Administrator
  • Pesapal
  • Posts: 404

At times you may experience cases where your application does not get updated when a transaction is made via PesaPal. For example, a client makes a payment via your app using mobile money, the transaction reads as COMPLETE on your PesaPal merchant dashboard yet on your application the status reads as UNPAID/PENDING/PROCESSING etc etc.

There are a number of reasons this may happen;
1. Incomplete application development.
2. Wrong system configurations.
3. Server restrictions.
4. Bugged application.

Incomplete application development.
In this case, it means as a developer, there are a few key things you might have left out when working on your system. There are 2 key functions you need to take care of regarding status updates.

  1. Callback code - Your callback page needs to call the Pesapal status update APIs. What's a callback page? This is the page users/clients are redirected to immediately they make a payment. In simple terms this is the success page. After a user is redirected to this page, PesaPal appends 2 things on this callback URL; pesapal_merchant_reference and pesapal_transaction_tracking_id. You are then required to check the status of the transaction using these parameters. It's advicable to use either QueryPaymentDetails or QueryPaymentStatus. Should you use QueryPaymentStatusByMerchantRef which requires only the pesapal_merchant_reference you might experience INVALID responses in instances where you have two or more transactions on the same merchant account sharing the same reference number. NB: If card payments read as PENDING on your app yet on PESAPAL they read as COMPLETED, it's highly likely that you've not implemented the callback correctly. Cards ideally COMPLETE or FAIL instantly. However, mobile payments may read as PENDING on callback page. Reason being by the time users are redirected to the callback page, PesaPal might still be waiting for the 3rd party mobile payment system to confirm the payment. This ideally takes 20sec.
  2. IPN code - An IPN (Instant Payment Notification) refers to an endpoint on your system that PesaPal sends alerts to whenever a status change is triggered on a particular transaction. It's somehow similar to callback page only that it's triggered behind the screen. Example, client makes a mobile money payment, get's redirected to callback page but a status check returns PENDING. Reason being, PesaPal is yet to get the confirmation from the mobile money provider. If the user decides to close the page, then 20secs later PesaPal gets the confirmation, PesaPal needs a way to alert your system that payment with reference XXX has changed status to either COMPLETED / FAILED. This is the main reason your application needs an IPN. When IPN is triggered, Pesapal appends 3 things to the IPN URL; pesapal_notification_type, pesapal_merchant_reference and the pesapal_transaction_tracking_id. Use the merchant reference and tracking id to check the status of the payment. The IPN documentation can be found here:

It's important to note that the callback URL has no pesapal_notification_type appended to it while the IPN has the parameter pesapal_notification_type appended to it.

Please do ensure you have implemented status update on both callback and IPN pages.

Wrong system configurations.
You might have added the callback and IPN codes correctly, but the set-up is incorrect. This mainly refers to IPN set-up.
  1. Ensure that IPN has been added on your merchant dashboard. See this on how to do so
  2. Make sure the IPN link is publicly accessible. Avoid having IPN links pointing to your localhost. Remember Pesapal is an external system.
  3. The subdomain where the payment originates/is captured MUST match the subdomain used as an IPN. For example, if the PesaPal iframe loads on, you can not set an IPN pointing to
  4. Do not set-up IPN on the wrong merchant account. We have and Add your IPN on the account that receives the payments.

Server restrictions
At times your server might have some certain level of security measures that blocks IPN calls from the PesaPal server. This will mostly happen on sites that have TLS/SSL. This being an external element, the solution lies with your server team to check on this.

A quick solution to this is also to change the IPN url from HTTPS to HTTP.

There are several ways to test server issues;
  1. Disable TLS/SSL and test IPN without this. Might not be the best solution, but it's some how the quickest. Please note we are not advocating for use on non-secured sites. This is just a test to see if TLS/SSL is the issue.
  2. If disabling TLS/SSL is not an option and you have access to another server (probably from a different host) move your project to this server and test on new server, make sure you update your IPN link.
  3. Your project might be too complex to move. In such a case, we suggest you try out our simple PHP code on a different server. You can even configure it on the current server to eliminate code issues.
  4. Adding logs to your IPN file. Logs can easily tell us if indeed the IPN URL was executed or not. You can write logs to your server or use email logs. It's best that the logging is done even before any set of system code is executed. Please check sample code we've shared above on how you can add some logs.
You can simply trigger an IPN call by doing 3 thing;
  • Login to your pesapal account, on the left menu click Account Settings > IPN settings. Locate your IPN link and click "RETRY". Follow the steps. Ideally, once you've forced IPN to ran, you will get a message similar to "Found and retried 3 pending IPNs." which means PesaPal found 3 IPN calls that were never acknowledged by your system. Retrying them actually forces the links to be triggered. If no IPN is found, this means, all is well or there is no payment linked to an IPN. Payments done before IPN was added can not trigger IPN calls, only payments that were done when the IPN existed and was active at the time of payment will be triggered. Please note only submitted/unacknowledged IPN calls can be retried.
  • Copy the IPN link and append the following details on the IPN URL pesapal_notification_type=CHANGE&pesapal_transaction_tracking_id=1111&pesapal_merchant_reference=2222. For example, if your IPN URL is, you should generate the link and run this on your browser or via postman. Check if logs are working correctly as your server should not block this call.
  • Making a payment. If IPN is configured, it will be executed.

NB; PesaPal does not store error logs related to external system. Hence it's important that you use the above methods to force an IPN call. If you ran the IPN via browser/postman and receive logs but when you force IPN by retrying and not get logs on the same. This means you are dealing with a server issue. Please contact your server team for assistance on this.

Bugged application.
It's important that you confirm your application has no fatal errors blocking code execution. Please enable Max errors on your system to confirm this.

In summary, causes 1,2 and 3 are the most common causes of failures.

For further assistance, contact us via This e-mail address is being protected from spambots. You need JavaScript enabled to view it. . For a quick resolution, ensure that;
  1. You've set-up logs and we have ways to check on the logs
  2. You've configured the sample code
  3. Attach a screenshot of your IPN settings page as seen on your dashboard.
  4. Share links to a test product on your system and a link to the example code configured in 2 above.
  5. Attach a sample transaction that did not trigger an IPN. Important details; Client names, email, merchant_reference and the date of the transaction. This will help us know if IPN was configured or this particular transaction.

Lazaro Ong'ele
Web Developer

Skype: Lazrotep
+254-020-249-5438 ; +254-706-191-729
Dagoretti Lane, Off Naivasha Road.

This e-mail address is being protected from spambots. You need JavaScript enabled to view it.
Last Edit: 1 year, 1 month ago by lazro.
The topic has been locked.
The following user(s) said Thank You: PhilipL
  • Page:
  • 1