ClickPesa

Collect payments with ClickPesa

CLICKPESA uses a hosted checkout: Centipid Billing asks ClickPesa for a checkout link and sends the payer’s browser to it. The payer completes the payment on ClickPesa’s page, and ClickPesa confirms the result on a webhook.

Available to ISPs in Tanzania (TZ), alongside AzamPay, PalmPesa, PawaPay, PesaPal, Relworx, ZenoPay, PayPal, and DPO.

Before you start

1. Complete ClickPesa merchant onboarding in an account owned by the ISP.
2. From the ClickPesa dashboard collect the API key and the client ID.
3. Confirm your workspace has a public HTTPS domain, so ClickPesa can reach the webhook.
4. Plan the walled garden. Because the payer’s own browser must load ClickPesa’s checkout page, a Hotspot subscriber who is not yet online cannot pay unless ClickPesa is reachable pre-authentication.

Configure the gateway

1. Open Settings → Payments → ClickPesa

   Select ClickPesa from the payment marketplace.

2. Enter the API key

   API key (required) is stored as a secret and is not echoed back into the form after saving.

3. Enter the client ID

   Client ID (required) identifies your ClickPesa account.

4. Allow ClickPesa through the captive walled garden

   Add ClickPesa’s checkout domain to the walled garden on every Hotspot router, then confirm from a device that is not yet authenticated. See Captive portal.

5. Run a controlled test payment

   Pay a small amount from the captive portal on a real unauthenticated device — not from an already-online laptop, which would not prove the walled garden works.

Credentials

Field	Required	Notes
API key	Yes	Secret.
Client ID	Yes	Identifies the ClickPesa account.

Callback URLs

Settings → Payments shows https://<your-host>/api/clickpesa/webhook. Register it in the ClickPesa dashboard, and confirm it is not blocked by a firewall or WAF rule.

What the payer must provide

Whatever ClickPesa’s own checkout page asks for — the payment method is chosen there, not in the captive portal. The amount and the order reference are fixed by Centipid Billing before the payer arrives.

The currency is your account’s configured currency, defaulting to TZS.

How a payment completes

1. Authorization token

   Centipid Billing exchanges the API key and client ID for a ClickPesa token. If a checkout request is rejected as unauthorized, the token is refreshed once and the request retried, so a merely expired token does not fail a payment.

2. Checkout link

   A checkout URL is generated for the order reference, amount, and currency, and a local transaction row is written against that reference.

3. Payment

   The payer’s browser is redirected to ClickPesa and the payment is completed there.

4. Confirmation

   ClickPesa posts the result to the webhook, which records the payment and applies the subscriber’s package.

Troubleshooting

Symptom	What it means	What to do
“…ClickPesa credentials are not configured.”	The API key or client ID is missing.	Enter both in Settings → Payments.
“…Failed to generate ClickPesa token.” or “…ClickPesa token missing in response.”	ClickPesa refused the credentials, or answered without a token.	Re-copy the API key and client ID. Confirm the merchant account is live.
“…ClickPesa API request failed with status: 401…”	The token was rejected even after one refresh.	Verify the credentials belong to the live account, not a sandbox one.
“…Checkout link not found in ClickPesa response”	ClickPesa accepted the request but returned no checkout URL.	Retry. If it persists, raise the order reference with ClickPesa.
The checkout page never loads on a Hotspot device	The walled garden does not allow ClickPesa.	Allow ClickPesa’s checkout domain pre-authentication — see Captive device cannot reach checkout.
Payment completed on ClickPesa, ledger empty	The webhook did not arrive or was not accepted.	Confirm the webhook URL is registered and publicly reachable, then see Payment troubleshooting.

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