PesaPal

Collect payments with PesaPal

PESAPAL uses a hosted checkout: Centipid Billing submits an order, sends the payer’s browser to PesaPal’s payment page, and reads the transaction status back from PesaPal before crediting anything.

PesaPal is offered in 14 countries in the catalog — Kenya, Uganda, Rwanda, Tanzania, Zambia, Malawi, Benin, Burkina Faso, Cameroon, DR Congo, Republic of the Congo, Senegal, Sierra Leone, and Zimbabwe.

Before you start

1. Complete PesaPal merchant onboarding in an account owned by the ISP.
2. Collect the consumer key and consumer secret from the PesaPal dashboard.
3. Confirm your workspace has a public HTTPS domain. PesaPal validates the IPN URL when it is registered, and rejects one it cannot accept.
4. Plan the walled garden: the payer’s browser must reach PesaPal’s page, so a Hotspot subscriber who is not yet online cannot pay unless PesaPal is reachable pre-authentication.

Configure the gateway

1. Open Settings → Payments → PesaPal

   Select PesaPal from the payment marketplace.

2. Enter the consumer key and consumer secret

   Both are required. The secret is stored as a secret and is not echoed back into the form after saving.

3. Save — the IPN URL registers itself

   Saving registers your IPN (Instant Payment Notification) URL with PesaPal and stores the id it issues. Every order carries that id, so this step is what makes checkout possible at all. If registration fails you are told so on this page, with PesaPal’s reason.

4. Run a controlled test payment

   Pay a small amount from the captive portal on an unauthenticated device, and confirm the payment reaches the ledger.

Credentials

Field	Required	Notes
Consumer key	Yes	From the PesaPal dashboard.
Consumer secret	Yes	Secret.

Both gate the switch. The IPN id is not a field — it is registered for you and stored automatically.

Callback URLs

Nothing to paste into the PesaPal dashboard by hand. The order carries its own return address, and the IPN URL — https://<your-host>/api/pesapal/webhook — is registered with PesaPal when you save your credentials.

Note

The IPN is re-registered automatically if your workspace domain changes, so notifications follow the move. If a re-registration fails while a working id is already stored, payments keep running on the stored id rather than stopping.

The notification is not what credits a payment: the transaction status is read back from PesaPal. But PesaPal will not accept an order without a registered IPN id at all, which is why registration gates checkout.

What the payer must provide

A phone number, and an email address when one is available — both are sent as the billing address on the order. The payment method itself is chosen on PesaPal’s page: card, mobile money, or Airtel, depending on what PesaPal has enabled for your account.

How a payment completes

1. Submit order

   Centipid Billing authenticates, submits the order with the amount, the reference, the billing address, and the registered IPN id, and receives a redirect URL.

2. Payment

   The payer completes the payment on PesaPal’s page.

3. Verification

   The transaction status is read back from PesaPal by its order tracking id. Only a completed status records a payment and applies the package.

Troubleshooting

Symptom	What it means	What to do
“…registering the Pesapal IPN URL failed: …” when saving	PesaPal refused the IPN URL. Its own reason follows the message.	Confirm your workspace domain is a public HTTPS address that resolves from outside your network, then save again.
“Payment failed: could not register the Pesapal IPN URL…” at checkout	No IPN id is stored and registration failed just now. No payer was charged.	Re-save your PesaPal credentials and read the error there; it is the same failure with more room to act on it.
“Payment failed: Unable to authenticate with Pesapal”	PesaPal rejected the consumer key or secret.	Re-copy both from the dashboard. Confirm the account is live.
“Payment failed: No redirect URL received…”	PesaPal accepted the order but returned no payment page.	Retry, then raise the reference with PesaPal.
The payment page never loads on a Hotspot device	The walled garden does not allow PesaPal.	Allow PesaPal’s domain pre-authentication — see Captive device cannot reach checkout.
“Payment not successful”	The status read back from PesaPal was not a completed payment.	Check the transaction on the PesaPal dashboard. Nothing is credited.
“Payment reference not found”	The reference has no matching local checkout.	Raise it with support with the PesaPal tracking id.

For every gateway’s fields in one place, see the credential reference.