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

# ClickPesa

> Configure ClickPesa hosted checkout for Tanzanian mobile money and bank payments.

# 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

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

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

  <Step title="Enter the client ID">
    **Client ID** (required) identifies your ClickPesa account.
  </Step>

  <Step title="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](/network/captive-portal).
  </Step>

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

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

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

  <Step title="Checkout link">
    A checkout URL is generated for the order reference, amount, and currency,
    and a local transaction row is written against that reference.
  </Step>

  <Step title="Payment">
    The payer's browser is redirected to ClickPesa and the payment is completed
    there.
  </Step>

  <Step title="Confirmation">
    ClickPesa posts the result to the webhook, which records the payment and
    applies the subscriber's package.
  </Step>
</Steps>

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

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