VibeFox Hubtel for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later with the cURL extension. The module refuses to install without them.
Currency: Ghana cedi (GHS) only. The payment method is hidden at checkout for other currencies. Keep the number of decimals of the GHS currency at 2, because Hubtel charges whole pesewas.
Hubtel account: a Hubtel business account with API keys (API ID and API Key) and the merchant account number (POS Sales ID). The keys are in the Hubtel business dashboard at bo.hubtel.com under Programmable keys.
IP whitelisting: Hubtel answers its Transaction Status API only from whitelisted server IP addresses. Ask Hubtel (your account manager or support@hubtel.com) to whitelist the public IP address of your web server. Until then payments cannot be confirmed and no order is created.
No test environment: Hubtel has no public sandbox. All payments are real.
Cron: a server cron job that calls the cron URL of the module every 5 minutes is recommended for the background payment checks (see Configuration).
VibeFox license key: bought on vibefox.net. One key works on one domain.
Installation
1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.
2. When the upload finishes, click Configure, or find VibeFox Hubtel Pay Gateway in the module list later and click Configure.
3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).
4. Enter the API ID, API Key and merchant account number (POS Sales ID).
5. Ask Hubtel support to whitelist your server IP for the Transaction Status API.
6. Add the cron URL shown on the Configure page to the cron of your server.
7. Turn on Enable/Disable and click Save. The callback URL is sent to Hubtel with every payment, so nothing has to be configured in the Hubtel dashboard.
On install the module creates the order status Hubtel payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences.
Configuration
All settings are on the module page: Modules > Module Manager > VibeFox Hubtel Pay Gateway > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page warns you when the API ID, API Key or merchant account number is missing, and when the default currency of the shop is not GHS. In both cases Hubtel is hidden at checkout. It also warns you when the GHS currency uses more than 2 decimals.
Hubtel
Enable/Disable: Enable Hubtel payments turns the payment method on or off. Default: off.
Title: the payment method name the customer sees at checkout. It is also the payment method name stored in the order. Default: Mobile Money or card (Hubtel). Required: an empty title gives the error Enter a title for the payment method.
Description: the text shown under the payment method at checkout. Default: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. You will be redirected to Hubtel to complete the payment.
Hubtel API credentials
Copy the API ID and API Key from your Hubtel business dashboard: bo.hubtel.com > Programmable keys. The merchant account number is the POS Sales ID of your Hubtel account. The section also repeats the IP whitelisting notice.
API ID (Client ID): the API ID of your Hubtel programmable keys.
API Key (Client Secret): the API Key of your Hubtel programmable keys. Keep it private. The saved key is never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.
Merchant account number (POS Sales ID): payments are collected into this Hubtel account and checked against it.
Clear saved API Key: tick it and click Save to remove the saved API Key. An empty field keeps the saved value.
Payment confirmation
Callback URL: the callback tells your shop that a payment has been made. This URL is sent to Hubtel with every payment, so nothing has to be configured in the Hubtel dashboard. With friendly URLs it looks like https://your-shop/module/wcp_hubtel_pay/callback, possibly with a language code. It must be reachable from the internet: no password protection or firewall blocking Hubtel. The callback also works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.
Hubtel callbacks are not signed. The module takes only the payment reference from a callback; the reference must belong to a payment of your shop. The status, amount and transaction ID always come from the Hubtel Transaction Status API. The order is created as paid only after that API confirms the payment and its amount.
Background payment checks (cron): the cron URL with a secret token. Call it every 5 minutes from the cron of your server, for example with curl. Payments without a confirmation are then re-checked with Hubtel automatically: 20 minutes after the customer was sent to Hubtel, once more after an hour if the payment is still unpaid, and up to 5 times with growing delays when Hubtel could not be reached. Keep the URL private.
Advanced
Debug log: logs API calls and callbacks to logs/hubtel_p_debug.log.php in the module folder. The file cannot be opened from the web. Keys and customer data are not logged. Errors and warnings are always logged, even when this option is off. Default: off.
Log: shows the current size and the latest entries of the log. Click Clear log to empty it.
Delete data on uninstall: when on, uninstalling the module removes the settings and the log of this module. Hubtel data saved for orders and the order status Hubtel payment on hold always stay. Default: off.
Checkout
At the payment step the customer chooses the payment method (by default Mobile Money or card (Hubtel)) and confirms. The module creates a Hubtel checkout for the cart total in GHS and sends the customer to the Hubtel payment page. The payment shows there as Cart #, the cart number and your shop name. On the Hubtel page the customer pays with MTN MoMo, Telecel Cash, AirtelTigo Money, a Visa or Mastercard card or GhQR. No order exists yet at this point. Every confirmation at the payment step creates a new payment attempt with its own reference, and older Hubtel pages of the same cart stay payable.
After paying, the customer returns to your shop. The order is marked paid only after Hubtel confirms it through the Transaction Status API: by the callback, by the check made when the customer returns, by a background check or by the order page button. A callback and a return arriving at the same moment are handled one after the other, so the order is never created twice. The customer then sees the standard order confirmation page. If the order was put on hold, the page shows Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.
If Hubtel has not confirmed the payment yet when the customer comes back, a Payment confirmation page shows We are waiting for Hubtel to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. with the buttons Check again and Back to checkout. The order is created as soon as Hubtel confirms the payment. If Hubtel has already reported this payment attempt as failed, the customer goes back to the checkout with The Hubtel payment was not completed. You can try again or choose another payment method. The cart is kept.
If the customer presses Cancel on the Hubtel page, the module first checks whether the payment was made anyway. If not, the customer goes back to the checkout with The Hubtel payment was cancelled. You can try again or choose another payment method. The cart is kept. A later payment of the cancelled Hubtel page is still accepted.
If Hubtel cannot start the payment, the customer stays at checkout with a short message, for example Could not connect to Hubtel. Please try again in a moment., Hubtel could not start the payment. Please try again or choose another payment method. or, with wrong credentials, Hubtel payments are not available at the moment. Please choose another payment method. The details go to the log.
The module has no refunds from PrestaShop, no subscriptions, no saved cards and no choice of the payment channel inside the shop.
Orders
Order statuses
No order yet: the customer was sent to Hubtel and has not paid, or Hubtel has not confirmed the payment yet. Only the cart exists.
Payment accepted: the payment was confirmed for the exact cart total in GHS. The payment is recorded with the Hubtel transaction ID, and a note shows the amount, the Hubtel transaction, the payment method and the reference.
Hubtel payment on hold: Hubtel reported a paid amount that differs from the cart total, or the cart is not in GHS. The order was not marked paid; the amount Hubtel actually took is recorded as a payment, and a note explains the mismatch. Check the payment in the Hubtel dashboard and fulfil the order or refund it manually. If another attempt of the same cart is later paid for the right amount, the order moves to Payment accepted.
If another attempt of an order that is already paid is paid as well, the order is not changed. A note asks you to refund the duplicate in your Hubtel dashboard. A payment for a cancelled or refunded order adds a note, and the order is never reopened automatically. When Hubtel reports a payment as refunded, a note is added to the order.
Hubtel payment block
The order page shows a Hubtel payment block with all payment attempts of the order's cart: date, reference, Hubtel checkout, amount, Hubtel status, transaction and result. Below the attempts it lists the Hubtel notes of the order, newest first.
The button Check Hubtel payment status checks the latest attempts of the order (up to 5, newest first, stopping once the order is paid), applies the result and adds a note with the status of each attempt. The result is shown in the block. You need the right to edit orders; access to the Modules pages is not needed. The button is available once the order exists. A paid cart without an order is confirmed by the callback, the customer's return or the cron.
Refunds
Refunds from PrestaShop are not supported. Refund the payment in the Hubtel dashboard, then record the refund in PrestaShop. The standard PrestaShop refund buttons of the order page do not send money back through Hubtel.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Hubtel Pay Gateway is the first block on Modules > Module Manager > VibeFox Hubtel Pay Gateway > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-payment-hubtel and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).
If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.
One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.
Without an active key, Hubtel is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed, also by the background payment checks.
When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed for the license check. Uninstalling or resetting the module always removes the license key and license status.
Troubleshooting
Hubtel does not appear at checkout: check that the license is active, Enable/Disable is on, the API ID, API Key and merchant account number are filled in and the cart currency is GHS. In Payment > Preferences check that the module is allowed for GHS, the customer's country and the customer's group. The settings page shows a warning when the credentials or the currency are wrong.
The payment went through, but no order was created: the payment could not be confirmed. Turn on Debug log and look at the Log field on the module page. HTTP 401 or 403 on the status check means the API keys are wrong or the server IP is not whitelisted by Hubtel. Also check that the callback URL is reachable from the internet and that the cron URL is called. Once Hubtel answers, the next callback, background check or customer return creates the order.
Callback answers Unknown reference: the payment reference does not belong to a payment of this shop.
Callback answers Payment status unavailable: the Transaction Status API could not be reached or refused the request, or the cart was being confirmed by another request at the same moment. The payment is re-checked in the background after 5 minutes.
Callback answers Gateway not configured: the API ID, API Key or merchant account number is missing. Fill them in; the payment is re-checked in the background.
Callback answers Invalid request or Invalid ClientReference: the request did not contain a valid Hubtel callback.
The callback URL shows Method not allowed in the browser: this is normal. The URL accepts only requests from Hubtel.
The cron URL answers Forbidden: the token in the URL is wrong. Copy the cron URL exactly as the settings show it.
Order is Hubtel payment on hold: read the notes in the Hubtel payment block (see Order statuses), check the payment in the Hubtel dashboard and fulfil the order or refund it manually.
The customer sees an error when choosing Hubtel: turn on Debug log and look at the log. Wrong API keys give Hubtel payments are not available at the moment. A connection problem gives Could not connect to Hubtel. A cart in another currency gives Hubtel accepts payments in Ghana cedis (GHS) only. Please choose another payment method.
For developers: the hook actionWcpHubtelPayIcon changes the payment method icon, and actionWcpHubtelPayPaymentDescription changes the payment description on the Hubtel page (up to 100 characters).
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox Hubtel Pay Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the settings and the log of this module are removed. If it is off, all settings are kept for a later re-install. The Hubtel data saved for orders and the order status Hubtel payment on hold are always kept. Existing orders keep their payment notes and transaction IDs.
Hubtel is a trademark of its respective owner. This module is not affiliated with or endorsed by Hubtel.