VibeFox Hubtel for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later with the cURL extension.

Currency: Ghana cedi (GHS) only. The payment method is hidden at checkout when the order currency is not GHS. 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 orders stay without a status.

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

Cron: a server cron job that calls the cron URL of the extension 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

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_hubtel_pay-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_hubtel_pay.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_hubtel_pay-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Hubtel Pay Gateway and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the 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 in the Payment confirmation section 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.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_hubtel_pay.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Hubtel Pay Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key, the Hubtel credentials and the cron as in steps 3 to 7 for OpenCart 3. The settings page and its fields are the same in both versions. Only the callback URL and the cron URL are different (see Payment confirmation).

A new install starts with the payment method turned off.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Hubtel Pay Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings the page warns you when the API ID, API Key or merchant account number is missing, and when the default currency of the store is not GHS. In both cases Hubtel is hidden at checkout. It also warns you when the GHS currency uses more than 2 decimals (set it in System > Localisation > Currencies). Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must not be empty and at most 128 characters (Enter a title for the payment method (1 to 128 characters).), Sort Order must be a whole number, Total a number, 0 or greater, and the geo zone and order statuses must exist; otherwise nothing is saved. If the payment method is turned on without the credentials, the settings are saved with a warning.

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.

Description: the text shown to the customer at the Confirm Order step, above the confirm button, next to the Mobile Money and card icon. Default: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. You will be redirected to Hubtel to complete the payment.

Sort Order: the position of Hubtel among the payment methods at checkout. Leave it empty or enter a whole number.

Geo Zone: offer Hubtel only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before Hubtel is offered. Leave it empty for no minimum.

Hubtel API credentials

Copy the API ID and API Key from your Hubtel business dashboard: bo.hubtel.com > Programmable keys (the section links there). 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. To remove the saved key, tick Clear saved API Key under the field and click Save.

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

Payment confirmation

Callback URL: the callback tells your store 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. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_hubtel_pay/callback, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_hubtel_pay/payment/wcp_hubtel_pay.callback. It is built from the storefront address of your OpenCart installation. It must be reachable from the internet: no password protection or firewall blocking Hubtel. The callback also works while the store is in maintenance mode: OpenCart 3 lets payment extension requests through, and on OpenCart 4 the extension adds a startup action that lets the callback, the cron URL and the customer's return from Hubtel through.

Hubtel callbacks are not signed. The extension takes only the payment reference from a callback; the reference must belong to a payment 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.

Background payment checks (cron): the cron URL with a secret token, created when the extension is installed. 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. On OpenCart 4 the cron URL has the route extension/wcp_hubtel_pay/payment/wcp_hubtel_pay.cron instead of extension/payment/wcp_hubtel_pay/cron; copy it exactly as the settings show it. Keep the URL private. The URL answers with a short line such as OK checked=0.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only after Hubtel has confirmed the payment. Each field below lists your OpenCart order statuses.

Order status after payment: the status set after Hubtel confirmed the payment of the exact order total in GHS. Default: Processing.

Hubtel payment on hold status: the status set when Hubtel reports a paid amount that differs from the order total, or the order is not in GHS. A note in the order history explains it. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Advanced

Debug log: logs API calls and callbacks to hubtel_p_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web, and at 5 MB it is moved to hubtel_p_debug.old.log.php. 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 extension removes the settings and the log of this extension. The Hubtel payment attempts saved for orders always stay. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. The API Key is not exported.

Import: paste previously exported JSON and click Import to restore the settings. The saved API Key is kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Mobile Money or card (Hubtel)). At the Confirm Order step the customer sees the icon and your description. OpenCart creates the order at this step, still without a status. When the customer clicks Confirm Order, the extension 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 store 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 Confirm Order creates a new payment attempt with its own reference, and older Hubtel pages stay payable.

On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page.

After paying, the customer returns to your store. 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 payment is never applied twice. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update, and the customer sees the OpenCart order success 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 gets its status 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, and the order stays without a status.

If the customer presses Cancel on the Hubtel page, the extension 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.

On OpenCart 4 the messages about a cancelled or failed payment are shown above the checkout page. OpenCart 3 creates a new order every time the Confirm Order step is shown; OpenCart 4 updates the order of the checkout, so after a cancel or a failed payment the customer pays the same order with a new payment attempt. Before a new attempt, the extension asks Hubtel about the unconfirmed attempts of this order and of earlier orders of the same cart (last 24 hours). If one of them turns out to be paid, that payment is applied and the customer goes to the success page instead of paying twice. A change of the cart, including a new quantity, counts as a new cart that needs its own payment.

OpenCart 4 keeps the order in the checkout until the success page is shown. If that order was closed without a payment meanwhile (for example you cancelled it), the customer is sent back to the checkout with The Hubtel payment was not completed. You can try again or choose another payment method., and the next Confirm Order pays a new order. If the order is already paid and the cart now holds a new purchase, Confirm Order reloads the checkout page and the next Confirm Order pays a new order. A paid order is never shown as paid for a different cart.

If Hubtel cannot start the payment, the customer stays at the Confirm Order step with a short message above the button, 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 extension has no refunds from OpenCart, no subscriptions, no saved cards and no choice of the payment channel inside the store.

Orders

Order statuses

No status (missing order): the customer was sent to Hubtel and has not paid, or Hubtel has not confirmed the payment yet. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Order status after payment (default Processing): the payment was confirmed for the exact order total in GHS. A note shows the amount, the Hubtel transaction, the payment method and the reference.

Hubtel payment on hold status (default Pending): Hubtel reported a paid amount that differs from the order total, or the order is not in GHS. The order was not marked paid, 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 order is later paid for the right amount, the order moves to Order status after payment.

If another attempt of an order that is already paid is paid as well, or another order of an already paid cart is paid, the paid order is not changed. A note asks you to refund the duplicate in your Hubtel dashboard. A payment for an order you have moved to another status (for example cancelled) adds a note, and the order is never reopened automatically. When Hubtel reports a payment as refunded, a note is added to the order.

Notes are entries in the order History that the customer does not see.

VibeFox Hubtel Pay Gateway tab

In Sales > Orders open an order paid with Hubtel. At the bottom of the order page, next to History and Additional, the VibeFox Hubtel Pay Gateway tab lists the Hubtel payment attempts of the order: date, reference and Hubtel checkout, amount, Hubtel status, transaction and result. Below the attempts it lists the Hubtel notes of the order, newest first. The tab is shown to users who have access to the extension.

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 tab. You need the right to modify orders (Sales > Orders, set in System > Users > User Groups). The button also works for an order without a status. A status set by this button is written directly, without order e-mails or stock update; the callback, the customer's return and the cron set it the standard way.

Refunds

Refunds from OpenCart are not supported. Refund the payment in the Hubtel dashboard, then record the refund in OpenCart. Product returns in Sales > Returns do not send money back through Hubtel.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Hubtel Pay Gateway is the first block on Extensions > Extensions > Payments > VibeFox Hubtel Pay Gateway > Edit, 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 store. Below them are the line Product: opencart-payment-hubtel and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store 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. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected: payments already started are still confirmed, also by the background payment checks.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: 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 the extension 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 order currency is GHS. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings. The settings page shows a warning when the credentials or the currency are wrong.

The payment went through, but the order stays without a status: the payment could not be confirmed. Turn on Debug log and look at the Log field on the extension 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, customer return or Check Hubtel payment status sets the order status.

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

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. After a re-install with Delete data on uninstall on, the token is new.

Order is in the on hold status: read the notes in the VibeFox Hubtel Pay Gateway tab (see Order statuses), check the payment in the Hubtel dashboard and fulfil the order or refund it manually.

The customer sees an error after Confirm 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. An order in another currency gives Hubtel accepts payments in Ghana cedis (GHS) only. Please choose another payment method. This payment method is not available. Please reload the checkout page. means the checkout no longer matches the order, or the payment method was turned off meanwhile.

For developers: the OpenCart event wcp_hubtel_pay_icon changes the payment method icon, and wcp_hubtel_pay_payment_description changes the payment description on the Hubtel page.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Hubtel Pay Gateway. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the order statuses of the Orders section, which return to their defaults on a re-install. The OpenCart event of the extension is removed too (on OpenCart 4 its events and its startup action, which lets the callback, the cron URL and the customer's return through in maintenance mode). If Delete data on uninstall is on, the other settings (title, description, API credentials, cron token, debug log switch) and the log are removed. If it is off, they are kept for a later re-install. The Hubtel payment attempts of orders are always kept, so late callbacks and checks still work after a re-install. Existing orders keep their payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Hubtel Pay Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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