VibeFox Hubtel for Adobe Commerce — 帮助

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL and JSON extensions.

Currency: Ghana cedi (GHS) only. The payment method is hidden at checkout for other currencies. Hubtel charges whole pesewas, and the module compares the order total with the paid amount to the pesewa.

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 [email protected]) to whitelist the public IP address of your web server. Until then payments cannot be confirmed and the orders stay in Pending Payment.

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

Magento cron: the Magento cron must run. The module uses it for the background payment checks every 5 minutes.

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

Installation

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-hubtel-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/HubtelPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_HubtelPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Hubtel Pay Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter the API ID, API Key and merchant account number (POS Sales ID). Ask Hubtel support to whitelist your server IP for the Transaction Status API. Set Enable to Yes and click Save Config. The callback URL is sent to Hubtel with every payment, so nothing has to be configured in the Hubtel dashboard.

The module adds the Mobile Money or card (Hubtel) payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates one table for the Hubtel payment attempts. It does not change the currency of your store.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Hubtel Pay Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a title for the payment method (1 to 128 characters).); a Sort Order that is not a whole number; a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater.

When Enable is Yes, the Payment confirmation row warns you: Hubtel: enter the API ID, API Key and merchant account number. when a credential is missing, and Hubtel accepts GHS only. Other currencies are hidden at checkout. when the store currency is not GHS. In both cases Hubtel is hidden at checkout.

Enable: shows or hides Hubtel at checkout. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Mobile Money or card (Hubtel). Required, at most 128 characters.

Description: shown in the payment method list at checkout, under the payment method when the customer selects it. Default: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. You will be redirected to Hubtel to complete the payment. Below it the customer also sees You will be redirected to Hubtel to complete the payment securely.

API ID (Client ID): the API ID of your Hubtel programmable keys (bo.hubtel.com > Programmable keys).

API Key (Client Secret): the API Key of your Hubtel programmable keys. Keep it private. Magento stores it encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved key, type a new value to change it. To delete the saved key, clear the field and click Save Config.

Merchant account number (POS Sales ID): the POS Sales ID of your Hubtel account. Payments are collected into this Hubtel account and checked against it. The note under the field reminds you: Ask Hubtel to whitelist this server IP for the Transaction Status API. Hubtel has no public sandbox.

Payment confirmation: shows the Callback URL (sent with each payment). It is the storefront URL of the default store view, for example https://your-store/wcphubtelpay/callback/index/; the URL sent with a payment is built for the store view of the order. It must be reachable from the internet: no password protection or firewall blocking Hubtel. The row also reminds you that the Magento cron checks pending payments every 5 minutes, that Hubtel must whitelist your server IP for the Status API and that refunds are made in the Hubtel dashboard.

Hubtel callbacks are not signed. The module takes only the payment reference from a callback; the reference must belong to a payment attempt of your store. The status, amount and transaction ID always come from the Hubtel Transaction Status API. The order is invoiced only after that API confirms the payment and its amount.

Payment from Applicable Countries: All Allowed Countries (the default) offers Hubtel for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Hubtel only for billing addresses in these countries.

Minimum Order Total: offer Hubtel only from this order total, in the base currency of your store. Empty means no minimum.

Maximum Order Total: offer Hubtel only up to this order total, in the base currency. Empty means no maximum.

Sort Order: the position among the payment methods at checkout. A whole number.

Debug log: logs API calls and callbacks to var/log/hubtel_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Keys and customer contact data are not logged. Errors and warnings are always logged, even when this option is No. Default: No.

Log: shows the current size and the latest entries of the log. Click Clear log to empty it.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. The Hubtel payment attempts always stay. Default: No.

Background payment checks

The Magento cron runs the Hubtel check every 5 minutes. Payments without a confirmation are 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 (15, 30, 45, 60 and 75 minutes) when Hubtel could not be reached. No cron URL has to be set up.

Checkout

At the payment step the customer chooses the payment method (by default Mobile Money or card (Hubtel)) and clicks Place Order. Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then 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 payment attempt has its own reference.

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 button on the order page. A callback and a return arriving at the same moment are handled one after the other, so the order is never invoiced twice. Magento then creates the invoice with the Hubtel transaction ID, the order becomes Processing and the order e-mail is sent. The customer sees the standard order success page. If the order was put on hold, the customer sees Your Hubtel payment was received and is being reviewed by the store. A customer who comes back in another browser lands on the home page with Your Hubtel payment has been received.

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. There is no need to pay again. with the links Check again and Back to checkout. The order stays in Pending Payment and is confirmed as soon as Hubtel confirms the payment.

If the customer presses Cancel on the Hubtel page, the module first checks whether the payment was made anyway. If not, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with The Hubtel payment was cancelled. You can try again. If Hubtel reports the payment as failed, the order is cancelled the same way and the message is The Hubtel payment was not completed. You can try again. If Hubtel cannot be reached at that moment, the customer sees the Payment confirmation page and the order waits for the next check.

Before a new attempt for the same cart, the module checks the earlier Hubtel pages of that cart. If one of them is paid already, no new payment is started: the new order is cancelled and the customer sees Your cart has already been paid with order # and the order number. If Hubtel cannot be reached for this check, the customer sees Hubtel status is unavailable. Please wait before paying again.

If the payment cannot be started, the order is cancelled, the cart is restored and the customer sees a short message in the cart, for example Hubtel could not start the payment. Please try again or choose another payment method. or, when the order is not in GHS or the credentials are missing, Hubtel payments are unavailable. Hubtel accepts GHS only. The details go to the log.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), the Hubtel page cannot be closed through the API. If that page is paid later, the order is not reopened, and a note asks you to refund the payment in Hubtel.

The module works with the standard Magento checkout. It has no online refunds from Magento, no subscriptions, no saved cards and no choice of the payment channel inside the store. Hubtel is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Hubtel, but Hubtel has not confirmed the payment yet. There is no invoice.

Processing: the payment was confirmed for the exact order total in GHS. The invoice is created with the Hubtel transaction ID as the transaction ID, and a note shows the amount, the Hubtel transaction and the reference.

On Hold: Hubtel reported a paid amount that differs from the order total, or the order is not in GHS. No invoice is created, and a note shows the amount Hubtel reported. Check the payment in the Hubtel dashboard, then fulfil the order or refund the payment there. If another attempt of the same order is later paid for the right amount, the order is released from hold and invoiced.

Canceled: the customer cancelled on the Hubtel page, Hubtel reported the payment as failed, the payment could not be started, or the order was cancelled in Magento.

Closed: the order was fully refunded with a credit memo.

If another attempt of an order or cart that is already paid is paid as well, or a payment arrives for a cancelled order, the order is not changed or reopened. A note asks you to review and refund the duplicate in Hubtel. When Hubtel reports a payment as refunded, a note is added once. The notes are order comments that the customer does not see.

Hubtel payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, after the confirmation, Hubtel reference and Hubtel transaction. The customer sees only the payment method title.

The Information tab of the order also shows Hubtel payment history: all payment attempts of the order with date, reference, Hubtel checkout ID, amount in pesewas, currency, Hubtel status, transaction and result. The button Check Hubtel payment status checks the latest attempts of the order (up to 5, newest first, stopping once one is paid), applies the result and adds a note with the result of each attempt. It is shown to Admin users whose role allows editing orders.

Refunds

Online refunds from Magento are not supported. Refund the payment in the Hubtel dashboard, then create a credit memo with Refund Offline in Magento. A full refund closes the order.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Hubtel Pay Gateway is the first row of the VibeFox Hubtel Pay Gateway group in Stores > Configuration > Sales > Payment Methods, 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: magento-payment-hubtel and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. 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 order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: payments already started are still confirmed, also by the background payment checks and the order page button.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Hubtel does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that the API ID, API Key and merchant account number are filled in and that the store currency is GHS. The Payment confirmation row shows a warning when the credentials or the currency are wrong. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

The payment went through, but the order stays Pending Payment: the payment could not be confirmed. Set Debug log to Yes and look at the Log field. A refused status check usually means that the API keys are wrong or that the server IP is not whitelisted by Hubtel. Also check that the callback URL is reachable from the internet and that the Magento cron runs. Once Hubtel answers, click Check Hubtel payment status on the order page, or wait for the next callback or background check.

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

Callback answers Payment status unavailable: the Transaction Status API could not be reached or refused the request (for example missing credentials or a server IP that is not whitelisted), 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 Invalid request: 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 return page shows Invalid Hubtel return token: the return link was changed or does not belong to this order. The payment is still confirmed by the callback or the background check.

Callbacks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the callback URL too. After the store is open again, the customer's return, the background checks and the order page button confirm the payment.

Order is On Hold: read the order notes (see Order statuses), check the payment in the Hubtel dashboard and fulfil the order or refund it manually.

The customer is back in the cart with an error after Place Order: set Debug log to Yes and look at the log. Wrong credentials or a connection problem give Hubtel could not start the payment. An order in another currency gives Hubtel payments are unavailable. Hubtel accepts GHS only. The order of that attempt is cancelled.

The Refund button is missing on the credit memo: online refunds are not supported. Refund the payment in the Hubtel dashboard, then use Refund Offline.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

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

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_HubtelPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_HubtelPayment to remove the data, then bin/magento module:disable Vibefox_HubtelPayment, delete the folder app/code/Vibefox/HubtelPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a re-install. The table of Hubtel payment attempts is always kept. Existing orders keep their invoices, payment notes and transaction IDs.

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