Pesapal payment notifications and status checks
Why a Pesapal payment needs a registered IPN address and a status check before a Kenyan business counts it, the status codes and set-up errors.
By Achekam · · 4 min read · For Running a business businesses in Kenya
A customer pays through Pesapal, the browser returns to your website, and the screen says thank you. It is tempting to treat that as the end of the story and mark the order paid.
Pesapal's own design says otherwise. The return to your site and the notification your server receives both tell you that something happened to the payment. Neither tells you what. Before a payment counts, your system has to ask Pesapal for its status. This article explains why, how the notification set-up works, what the status codes mean and some common set-up mistakes.
Why the IPN is mandatory
Pesapal says it is mandatory to configure an IPN (payment notification) URL, so that Pesapal can notify the merchant's servers whenever a transaction's status changes. Pesapal gives the reasons: the customer may be disconnected, may close the browser during payment, or the transaction may be rejected.
Each of those leaves the customer's browser unable to bring the news back to your website. The IPN does not depend on the customer's browser at all. It goes from Pesapal's servers to yours, so your system learns that something has changed even when the customer has walked away.
Registering it and the notification ID
Pesapal says the IPN URL must be registered before order requests are submitted, and that registration returns an IPN ID that must be sent as the notification_id with every order. The IPN can be registered as a GET or POST callback, through the RegisterIPN endpoint or Pesapal's online registration forms.
Two further rules shape the set-up:
- Reachability. Pesapal says the IPN URL must be publicly reachable. Where server rules block external systems, the merchant must whitelist calls from the pesapal.com domain, because whitelisting by IP address is not feasible: Pesapal's IP addresses may change without notice.
- Unique order references. Pesapal says each order needs a merchant reference that is unique for every order request, up to 50 characters, using only letters, digits, dashes, underscores, dots and colons. Other required fields include the currency, the amount, a description of up to 100 characters, a callback_url, the notification_id and a billing address with at least a phone number or e-mail address.
The unique reference is what lets you match Pesapal's answer to the right invoice later, so never reuse one, even for a retry of the same invoice.
The callback carries no status
Pesapal says, for security reasons, the callback URL and IPN calls do not carry the payment status, so the merchant must fetch it with the GetTransactionStatus API. After the callback or IPN, the merchant checks the payment status with GetTransactionStatus, using the OrderTrackingId.
This is a deliberate design. A message that said "paid" could be forged by anyone who knew your address; a message that says only "ask us about this order" is worthless to a forger, because the answer comes from Pesapal directly.
Pesapal also sets out how each endpoint should respond. The IPN endpoint returns a JSON string confirming receipt, with status 200 if it processed the notification or 500 if there was a problem. The callback page, which the customer sees, should not return JSON but show the customer the payment details.
Status codes: invalid, completed, failed, reversed
Pesapal's transaction status codes are 0 INVALID, 1 COMPLETED, 2 FAILED and 3 REVERSED. The status response also gives the payment method, amount, confirmation code, masked payment account and currency.
| Code | Meaning | What the business does |
|---|---|---|
| 0 INVALID | Pesapal reports the transaction as invalid | Do not record a payment |
| 1 COMPLETED | Paid | Record the payment and keep the confirmation code |
| 2 FAILED | The attempt failed | Leave the invoice open; the customer may try again |
| 3 REVERSED | A payment was reversed | Investigate and reverse any receipt recorded |
Keep the confirmation code from every completed payment. You will need it if the payment is ever refunded, as explained in refunding a Pesapal payment.
How Achekam asks Pesapal before recording
A Kenyan business can take Pesapal card and mobile-money payments in shillings in Achekam, with each payment confirmed with Pesapal before it counts. Because Pesapal notifications carry no status, Achekam asks Pesapal for the transaction status before recording a payment.
If a notification never arrives, the payment is still picked up: for M-Pesa, Paystack and Pesapal, the server asks the provider about open payments on a schedule and while the pay page is open. Once verified, the payment is recorded as a receipt against the invoice, debiting the Pesapal clearing account and crediting trade receivables, so the invoice shows as paid or part-paid in the books without anyone retyping it. The amount is checked against what the link asked for, and a repeated notification never pays twice.
Common set-up errors
- Orders sent before the IPN is registered, or without the notification_id, so no notifications arrive.
- A firewall that blocks Pesapal, or an attempt to whitelist Pesapal by IP address instead of by its domain.
- Reused merchant references, which make it impossible to match a status to the right order.
- Treating the return to the website as proof of payment, without a status check.
- An IPN endpoint that does not reply as Pesapal expects, leaving the notification unacknowledged.
- A description longer than Pesapal allows.
Tour operators and others taking deposits online will find a worked set-up in taking Pesapal payments in Kenyan travel.
Pesapal's guide to registering an IPN URL explains how to register the notification address so your system hears about status changes even when the customer's session drops.
General guidance only, not advice on your own circumstances. Tax and payroll rules change: check the current position with the authority or your adviser.
