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

# Hubtel

> Configure Hubtel mobile money collections for Ghana, including how the payer's network is detected.

# Collect payments with Hubtel

`HUBTEL` sends a mobile money prompt to the payer's phone through Hubtel's
merchant account API. The payer approves it on their handset, and Hubtel
confirms the result on a callback.

Available to ISPs in **Ghana (GH)**, alongside MTN MoMo, PawaPay, Paystack,
PayPal, and DPO.

## Before you start

1. Complete Hubtel merchant onboarding in an account owned by the ISP.
2. In the Hubtel dashboard open **API & Integrations → API Credentials** and
   collect the **client ID** and **client secret**.
3. Confirm your workspace has a public HTTPS domain, so Hubtel can reach the
   callback.

## Configure the gateway

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

  <Step title="Enter the client ID">
    **Hubtel client ID** (required) comes from API & Integrations → API
    Credentials.
  </Step>

  <Step title="Enter the client secret">
    **Hubtel client secret** (required) is stored as a secret and is not echoed
    back into the form after saving. The pair is sent as HTTP basic
    authentication on every request.
  </Step>

  <Step title="Run a controlled test payment">
    Pay a small amount from the captive portal and confirm the prompt arrives on
    the handset and the payment reaches the ledger.
  </Step>
</Steps>

## Credentials

| Field                | Required | Notes                                 |
| -------------------- | -------- | ------------------------------------- |
| Hubtel client ID     | Yes      | API & Integrations → API Credentials. |
| Hubtel client secret | Yes      | Secret.                               |

## Callback URLs

Settings → Payments shows `https://<your-host>/api/hubtel/callback`. It is also
sent with every payment request as the primary callback, so there is normally
nothing to register — but confirm it is not blocked by a firewall or WAF rule.

## What the payer must provide

**A Ghanaian mobile money number.** The network is detected from the number's
prefix, and a number whose prefix is not recognized is refused **before** any
request reaches Hubtel:

| Network    | Prefixes                          |
| ---------- | --------------------------------- |
| MTN        | `024`, `054`, `055`, `059`, `025` |
| Vodafone   | `020`, `050`                      |
| AirtelTigo | `026`, `056`, `057`, `027`        |
| Glo        | `023`                             |

Numbers are accepted with or without the `233` country code and with or without
a leading zero. The currency is your account's configured currency, defaulting
to `GHS`.

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

## How a payment completes

<Steps>
  <Step title="Request">
    Centipid Billing posts the charge to Hubtel's send-mobile-money endpoint
    with the amount, the payer's number, the detected channel, and a unique
    client reference.
  </Step>

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

  <Step title="Confirmation">
    Hubtel posts the outcome to the callback, which records the payment and
    applies the subscriber's package.
  </Step>
</Steps>

## Troubleshooting

| Symptom                                                                                     | What it means                                                                             | What to do                                                                                                                                              |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *"Hubtel credentials are not configured."*                                                  | The client ID or secret is missing.                                                       | Enter both in Settings → Payments.                                                                                                                      |
| *"A phone number is required to initiate a Hubtel payment."*                                | Checkout had no phone number.                                                             | Collect one before retrying.                                                                                                                            |
| *"Unable to determine the customer's mobile money network from the provided phone number."* | The prefix is not in the table above. No request was sent, and the payer was not charged. | Re-enter the number in Ghanaian format. If the prefix is genuinely new, raise it with support.                                                          |
| A message from Hubtel on a failed request                                                   | Hubtel refused the charge and its own error is shown.                                     | Read the message — it usually names the credential or the wallet at fault.                                                                              |
| *"Unable to reach Hubtel. Please try again in a moment."*                                   | The request could not connect.                                                            | Check outbound connectivity from the application host.                                                                                                  |
| Prompt approved, ledger stays empty                                                         | The callback did not arrive.                                                              | Confirm `https://<your-host>/api/hubtel/callback` is 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).