> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centipidbilling.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PesaPal

> Configure PesaPal hosted checkout, with the IPN URL registered for you when you save.

# 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 the most widely offered gateway 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

<Steps>
  <Step title="Open Settings → Payments → PesaPal">
    Select PesaPal from the payment marketplace.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Run a controlled test payment">
    Pay a small amount from the captive portal on an unauthenticated device, and
    confirm the payment reaches the ledger.
  </Step>
</Steps>

## 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.
</Note>

## 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Payment">
    The payer completes the payment on PesaPal's page.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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](/billing/payment-gateways/troubleshooting). |
| *"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](/billing/payment-gateways/credentials-reference).