Pesapal API 3.0

QuickstartZero to a completed sandbox payment in five steps.

AuthenticationGet a token, cache it correctly, and handle the three ways authentication fails.

Instant Payment NotificationsHow Pesapal notifies your server, and why that notification proves nothing.

STK PushTake a payment without sending the customer to a payment page.

ErrorsEight response shapes, and a catalogue of every error code.

TestingSandbox cards, shared credentials, and what the sandbox cannot simulate.

Why this exists

Every claim on this site was verified by making the request and recording the response. The captures are published alongside the documentation, so any statement here can be checked against what the API actually returned.

Notification URLs are never checked

Registering one validates its shape and nothing else. A mistyped URL reports itself as active and then silently never delivers a payment notification.

HTTP 200 means nothing

Wrong credentials, an unsupported currency and a declined order all return 200. There are eight distinct response shapes to handle.

A pending payment is an error

Querying an unpaid order returns payment_details_not_found. The same code is used for orders that genuinely do not exist.

Reusing an order id is dangerous

Resubmitting a merchant reference silently returns the original order and discards your new payload, including a changed amount.

Unofficial

This is a community project. It is not affiliated with, endorsed by, or maintained by Pesapal. For the official documentation, see developer.pesapal.com.

Findings were verified against the Pesapal sandbox in September 2026 and are documented in the research directory, including the probe scripts and every captured response.