PawaPay

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, Nigeria, Ethiopia, Gabon, Lesotho, and Mozambique.

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

1. Open Settings → Payments → PawaPay

   Select PawaPay from the payment marketplace.

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

3. Check your country is set

   PawaPay charges in your account’s billing currency, not one set on this form, and that currency must be one PawaPay accepts in your country. DR Congo accepts CDF or USD; every other country accepts one. An account with no currency set is charged the country’s default: Kenya KES, Uganda UGX, Tanzania TZS, Ghana GHS, Nigeria NGN, Rwanda RWF, Zambia ZMW, Malawi MWK, Sierra Leone SLE (an account set to the old SLL is charged in SLE), DR Congo CDF or USD, Ethiopia ETB, Lesotho LSL, Mozambique MZN, the CFA countries XOF or XAF. A checkout whose prices are in a currency PawaPay does not bill your country in is refused rather than charged in the wrong currency.

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

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.

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

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

2. Acceptance

   PawaPay answers ACCEPTED. The request is stored and polling is scheduled.

3. Authorization

   The payer approves on their handset.

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

Troubleshooting

Symptom	What it means	What to do
“Mobile money provider not selected or configured correctly.”	No correspondent reached the request, the one picked does not serve your country, or PawaPay does not serve your country at all.	Have the payer pick a provider. Confirm with PawaPay which correspondents your account may use, or use a different gateway in a country PawaPay does not serve.
“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.
“PawaPay bills in NGN here, but your prices are in USD…” (payers see “Mobile money is not set up correctly on this network.”)	Your account’s currency is not one PawaPay bills your country in.	Contact Centipid support to change your billing currency, then reprice your packages in it.
“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.