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

# PawaPay

> Configure PawaPay pan-African mobile money collections, with a single API token.

# Collect payments with PawaPay

`PAWAPAY` aggregates mobile money across much of Africa behind one API token.
Centipid Billing posts a deposit request, the payer authorizes on their handset,
and the deposit is polled to completion.

Offered in the country catalog for **Uganda, Rwanda, Ghana, Côte d'Ivoire,
Tanzania, Zambia, Malawi, Benin, Burkina Faso, Cameroon, DR Congo,
Republic of the Congo, Senegal, Sierra Leone, and Nigeria**.

## Before you start

1. Complete PawaPay merchant onboarding in an account owned by the ISP.
2. Collect the **API token** from the PawaPay dashboard.
3. Confirm which mobile money providers ("correspondents") PawaPay has enabled
   for your account — the payer picks one at checkout, and an unsupported choice
   is refused.
4. Confirm your account's country is set correctly. PawaPay requires both a
   three-letter country code and the matching currency, and both are derived
   from it.

## Configure the gateway

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

  <Step title="Enter the API token">
    **PawaPay API token** (required) is the only field. It is stored as a secret
    and is not echoed back into the form after saving.
  </Step>

  <Step title="Check your country is set">
    The currency is chosen from your country, not from a field on this form.
    Kenya bills `KES`, Uganda `UGX`, Tanzania `TZS`, Ghana `GHS`, Nigeria `NGN`,
    Rwanda `RWF`, Zambia `ZMW`, Malawi `MWK`, Sierra Leone `SLE`, DR Congo
    `CDF`, the CFA countries `XOF` or `XAF`.
  </Step>

  <Step title="Run a controlled test payment">
    Pay a small amount from the captive portal, choose a correspondent, and
    confirm the prompt arrives and the payment lands in the ledger.
  </Step>
</Steps>

## Credentials

| Field             | Required | Notes                                                           |
| ----------------- | -------- | --------------------------------------------------------------- |
| PawaPay API token | Yes      | Secret. The only field, and the only one that gates the switch. |

Requests go to `https://api.pawapay.io` in production and to
`https://api.sandbox.pawapay.io` everywhere else, so a sandbox token cannot be
tested against production or the other way round.

## Callback URLs

Settings → Payments shows `https://<your-host>/api/pawapay/callback`. Register
it with PawaPay.

<Note>
  PawaPay callbacks are best-effort and do go missing, so the callback is not
  what a payment depends on. Every accepted deposit is also polled: the captive
  portal queries it while the payer's browser is open, and a background job
  keeps polling after the payer has moved on. A payment therefore still
  completes when the callback never arrives.
</Note>

## What the payer must provide

* **A mobile money number**, normalized to the country's international format.
* **A correspondent** — the mobile money provider to charge. Checkout refuses to
  send a request without a supported one.

Authorization happens on the handset, so no PawaPay domain needs to be added to
the captive walled garden.

## How a payment completes

<Steps>
  <Step title="Request">
    A deposit is posted with a unique deposit id, the amount, the country and
    currency resolved from your account, the correspondent, and the payer's
    number. The deposit id is what everything afterwards reconciles against.
  </Step>

  <Step title="Acceptance">
    PawaPay answers `ACCEPTED`. The request is stored and polling is scheduled.
  </Step>

  <Step title="Authorization">
    The payer approves on their handset.
  </Step>

  <Step title="Confirmation">
    The deposit settles to `COMPLETED`, `FAILED`, or `REJECTED`. Only
    `COMPLETED` records a payment and applies the package; the failure reason
    PawaPay returns is stored against the transaction.
  </Step>
</Steps>

## Troubleshooting

| Symptom                                                         | What it means                                                               | What to do                                                                                                                                                     |
| --------------------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *"Mobile money provider not selected or configured correctly."* | No correspondent reached the request.                                       | Have the payer pick a provider. Confirm with PawaPay which correspondents your account may use.                                                                |
| *"PawaPay API token not configured."*                           | No token is saved.                                                          | Enter it in Settings → Payments.                                                                                                                               |
| *"PawaPay authentication failed. Check API token."*             | PawaPay rejected the token (HTTP 401).                                      | Re-copy it. Confirm it is a production token if this is production.                                                                                            |
| *"…country configuration error for PawaPay."*                   | Your country could not be resolved to a three-letter code.                  | Set the country correctly on your account.                                                                                                                     |
| *"Currency configuration error for your country with PawaPay."* | Your country is not one PawaPay bills in.                                   | Use a different gateway for that country.                                                                                                                      |
| *"PawaPay request failed."*, or a message from PawaPay          | PawaPay rejected the deposit and its own reason is shown when it sends one. | Read the message; it usually names the field or the correspondent at fault.                                                                                    |
| Deposit stays pending                                           | It has not reached a terminal state yet.                                    | Let polling settle it. `BUSY` and `NOT_FOUND` are transient — do not record a manual payment, and do not ask the payer to retry until the deposit is resolved. |

For every gateway's fields in one place, see the
[credential reference](/billing/payment-gateways/credentials-reference).