Hubtel

Collect payments with Hubtel

HUBTEL sends a mobile money prompt to the payer’s phone through Hubtel’s Direct Receive Money API, into the ISP’s own Hubtel merchant account. 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

Complete Hubtel merchant onboarding in an account owned by the ISP.
In the Hubtel dashboard open API & Integrations → API Credentials and collect the client ID and client secret.
Note your merchant account number, which Hubtel also calls the POS Sales ID. Every charge is made to this account, and Hubtel refuses charges that do not name it.
Confirm your workspace has a public HTTPS domain, so Hubtel can reach the callback.
Ask Hubtel to allow-list Centipid’s payment servers on your merchant account. Hubtel refuses every charge from an IP address it has not approved. Send your Hubtel account manager (or Hubtel support) your POS Sales ID and these six addresses:
```
157.245.47.145
165.227.224.60
144.126.225.36
178.128.162.87
178.128.162.201
206.189.22.251
```

Configure the gateway

Open Settings → Payments → Hubtel
Select Hubtel from the payment marketplace.
Enter the client ID
Hubtel client ID (required) comes from API & Integrations → API Credentials.
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.
Enter the merchant account number
Merchant account number (required) is your Hubtel POS Sales ID.
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.

Credentials

Field	Required	Notes
Hubtel client ID	Yes	API & Integrations → API Credentials.
Hubtel client secret	Yes	Secret.
Merchant account number	Yes	Your Hubtel POS Sales ID.

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

Request
Centipid Billing posts the charge to Hubtel’s receive-mobile-money endpoint for your merchant account, with the amount, the payer’s number, the detected channel, and a unique client reference.
Authorization
The payer approves the prompt on their handset.
Confirmation
Hubtel posts the outcome to the callback, which records the payment and applies the subscriber’s package.

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.
“Hubtel merchant account number (POS Sales ID) is not configured.”	The merchant account number is missing. No request was sent.	Enter your POS Sales ID in Settings → Payments → Hubtel.
“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.
“Hubtel blocked this payment request: this network’s Hubtel account has not approved our payment servers yet.”	Hubtel answered 403 before checking any credential: Centipid’s servers are not on your account’s IP allow-list. No money was taken.	Ask Hubtel to allow-list the six addresses under Before you start.
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.
“Hubtel did not confirm the request. If a prompt arrives on your phone, approve it; otherwise try again in a moment.”	Hubtel did not answer in time. The charge is not re-sent, because the prompt may already be on the phone; if the payer approves it, the callback still grants the package.	If it keeps happening, 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.

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