VibeFox Hubtel for WooCommerce — Help

Requirements

WordPress: 6.2 or later.

WooCommerce: 8.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Currency: Ghana cedi (GHS) only. The payment method is hidden at checkout for other currencies. Keep the WooCommerce number of decimals 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 orders stay Pending payment.

No test environment: Hubtel has no public sandbox. All payments are real.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_hubtel_pay folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Hubtel > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Enter the API ID, API Key and merchant account number (POS Sales ID).

6. Ask Hubtel support to whitelist your server IP for the Transaction Status API.

7. Turn on Enable/Disable. The callback URL is sent to Hubtel with every payment, so nothing has to be configured in the Hubtel dashboard.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Hubtel. Above the fields the page warns you when the API ID, API Key or merchant account number is missing, and when the store currency is not GHS. In both cases Hubtel is hidden at checkout. It also warns you when the store uses more than 2 decimals. In the list of payment methods the gateway is marked as needing setup until the credentials are filled in.

Enable/Disable: Enable Hubtel payments turns the payment method on or off. Default: off.

Title: the payment method name the customer sees at checkout. Default: Mobile Money or card (Hubtel).

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.

Merchant account number (POS Sales ID): payments are collected into this Hubtel account and checked against it.

Payment confirmation

The callback tells your store that a payment has been made. The callback URL shown in this section is sent to Hubtel with every payment, so nothing has to be configured in the Hubtel dashboard. It looks like https://your-site/wc-api/hubtel_pay/. It must be reachable from the internet: no maintenance mode, password protection or firewall blocking Hubtel.

Hubtel callbacks are not signed. The plugin takes only the payment reference from a callback; the reference must belong to an order of your store. The status, amount and transaction ID always come from the Hubtel Transaction Status API. The order is marked paid only after that API confirms the payment and its amount. If Hubtel cannot be reached, the payment is re-checked automatically in the background, and you can check it from the order screen with Order actions > Check Hubtel payment status.

Advanced

Debug log: Log API calls and callbacks to WooCommerce > Status > Logs, source wcp_hubtel_pay, without keys or customer data. Errors are always logged. Default: off.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Hubtel data saved on orders is kept). Default: off.

Checkout

The customer chooses the payment method (by default Mobile Money or card (Hubtel)) and places the order. The plugin creates a Hubtel checkout for the order total in GHS and sends the customer to the Hubtel payment page. The payment shows there as Order #, the order number and your site name. On the Hubtel page the customer pays with MTN MoMo, Telecel Cash, AirtelTigo Money, a Visa or Mastercard card or GhQR. Every click on Place order or Pay creates a new payment attempt with its own reference, and older Hubtel pages of the same order stay payable.

After paying, the customer returns to the order received page. 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 action. A callback and a return arriving at the same moment are handled one after the other, so the order is never completed twice. If Hubtel has not confirmed the payment yet, the 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. If the order was put on hold, it shows Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.

If the customer presses Cancel on the Hubtel page, the plugin first checks whether the payment was made anyway. If not, the customer goes back to the Pay for order page with the message The Hubtel payment was cancelled. You can try again or choose another payment method.

If Hubtel cannot start the payment, the customer sees 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 payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin has no refunds from WooCommerce, no subscriptions, no saved cards and no choice of the payment channel inside WooCommerce.

Orders

Order statuses

Pending payment: the customer was sent to Hubtel and has not paid yet, or Hubtel has not confirmed the payment yet.

Processing: the payment was confirmed. Orders with only virtual downloadable products become Completed, the WooCommerce default. The order note shows the amount, the Hubtel transaction, the payment method and the reference. The transaction ID is the Hubtel transaction ID.

On hold: Hubtel reported a paid amount that differs from the order total, or the order is not in GHS (note Hubtel amount/currency mismatch); or a payment arrived for an order that had been cancelled. The order was not marked paid. Check the payment in the Hubtel dashboard and complete or refund the order manually.

Failed: Hubtel reported that the latest payment attempt of a pending order failed, and the Transaction Status API confirms it is not paid. The customer can try again from the order. A failure reported only by a callback never fails an order.

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 cancelled or refunded order is never reopened automatically. When Hubtel reports a payment as refunded, a note is added to the order.

Payment checks

About 20 minutes after the customer is sent to Hubtel, a background check (WooCommerce Action Scheduler) asks Hubtel about the payment, in case the callback was lost and the customer did not come back. An unpaid attempt is checked once more after an hour. When the Hubtel API cannot be reached, the check is repeated up to 5 times with growing delays.

The order action Check Hubtel payment status checks the latest attempts of the order (up to 5, newest first), applies the result and adds a note with the status of each attempt.

Refunds

Refunds from WooCommerce are not supported. Refund the payment in the Hubtel dashboard, then create a manual refund in WooCommerce.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Hubtel. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

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 currency is GHS. On the Pay for order page the order currency counts. The settings page shows a warning when the credentials or the currency are wrong.

The payment went through, but the order stays Pending payment: the payment could not be confirmed. Open WooCommerce > Status > Logs, source wcp_hubtel_pay. 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. After fixing it, open the order and run Order actions > Check Hubtel payment status. The background checks also confirm the order once Hubtel answers.

Callback answers Unknown reference: the payment reference does not belong to an order of this store.

Callback answers Payment status unavailable: the Transaction Status API could not be reached or refused the request. The payment is re-checked in the background.

Order is On hold with an amount/currency mismatch note: Hubtel reported a paid amount that differs from the order total, or the order is not in GHS. Check the payment in the Hubtel dashboard and complete or refund the order manually.

The customer sees an error when placing the order: 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.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

For developers: the filter hubtel_p_icon changes the payment method icon, and hubtel_p_payment_description changes the payment description on the Hubtel page (up to 100 characters).

Uninstall

Deactivating the plugin keeps all data; only the pending background payment checks are cancelled. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings, the plugin's own options, pending background checks and the logs are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Hubtel data saved on orders is payment history and is always kept. Existing orders keep their payment notes and transaction IDs.

Hubtel is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Hubtel.