VibeFox Hubtel for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur avec l'extension cURL. Le module refuse de s'installer sans elles.

Devise : uniquement le cedi ghanéen (GHS). Le mode de paiement est masqué au moment du paiement pour les autres devises. Conservez à 2 le nombre de décimales de la devise GHS, car Hubtel facture des pesewas entiers.

Compte Hubtel : un compte professionnel Hubtel avec des clés d'API (API ID et API Key) et le numéro de compte marchand (POS Sales ID). Les clés se trouvent dans le tableau de bord professionnel de Hubtel sur bo.hubtel.com, sous Programmable keys.

Liste blanche IP : Hubtel ne répond à sa Transaction Status API que depuis des adresses IP de serveur inscrites sur liste blanche. Demandez à Hubtel (votre gestionnaire de compte ou support@hubtel.com) d'inscrire sur liste blanche l'adresse IP publique de votre serveur web. Tant que ce n'est pas fait, les paiements ne peuvent pas être confirmés et aucune commande n'est créée.

Pas d'environnement de test : Hubtel ne propose pas de bac à sable public. Tous les paiements sont réels.

Cron : une tâche cron serveur qui appelle l'URL cron du module toutes les 5 minutes est recommandée pour les vérifications de paiement en arrière-plan (voir Configuration).

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un domaine.

Installation

1. Dans le back office, allez dans Modules > Module Manager et cliquez sur Upload a module. Choisissez le fichier ZIP du module.

2. Une fois le téléchargement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Hubtel Pay Gateway dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).

4. Saisissez l'API ID, l'API Key et le numéro de compte marchand (POS Sales ID).

5. Demandez au support Hubtel d'inscrire l'IP de votre serveur sur liste blanche pour la Transaction Status API.

6. Ajoutez l'URL cron affichée sur la page Configure au cron de votre serveur.

7. Activez Enable/Disable et cliquez sur Save. L'URL de callback est transmise à Hubtel avec chaque paiement : rien n'est à configurer dans le tableau de bord Hubtel.

À l'installation, le module crée le statut de commande Hubtel payment on hold. PrestaShop propose un nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les limiter dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Hubtel Pay Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit si l'API ID, l'API Key ou le numéro de compte marchand est manquant, et si la devise par défaut de la boutique n'est pas GHS. Dans les deux cas, Hubtel est masqué au moment du paiement. Elle signale aussi si la devise GHS utilise plus de 2 décimales.

Hubtel

Enable/Disable : Enable Hubtel payments active ou désactive le mode de paiement. Par défaut : désactivé.

Title : le nom du mode de paiement que le client voit au moment du paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Mobile Money or card (Hubtel). Obligatoire : un titre vide donne l'erreur Enter a title for the payment method.

Description : le texte affiché sous le mode de paiement au moment du paiement. Par défaut : Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. Vous serez redirigé vers Hubtel pour finaliser le paiement.

Identifiants de l'API Hubtel

Copiez l'API ID et l'API Key depuis votre tableau de bord professionnel Hubtel : bo.hubtel.com > Programmable keys. Le numéro de compte marchand est le POS Sales ID de votre compte Hubtel. La section rappelle aussi l'avis sur la liste blanche IP.

API ID (Client ID) : l'API ID de vos clés programmables Hubtel.

API Key (Client Secret) : l'API Key de vos clés programmables Hubtel. Gardez-la confidentielle. La clé enregistrée n'est plus jamais affichée. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.

Merchant account number (POS Sales ID) : les paiements sont encaissés sur ce compte Hubtel et y sont vérifiés.

Clear saved API Key : cochez la case et cliquez sur Save pour supprimer l'API Key enregistrée. Un champ vide conserve la valeur enregistrée.

Confirmation du paiement

Callback URL : le callback informe votre boutique qu'un paiement a été effectué. Cette URL est transmise à Hubtel avec chaque paiement : rien n'est à configurer dans le tableau de bord Hubtel. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_hubtel_pay/callback, éventuellement avec un code de langue. Elle doit être accessible depuis Internet : aucune protection par mot de passe ni pare-feu bloquant Hubtel. Le callback fonctionne aussi lorsque la boutique est en mode maintenance et n'est pas bloqué par la restriction géographique de votre boutique.

Les callbacks de Hubtel ne sont pas signés. Le module ne retient du callback que la référence du paiement ; cette référence doit appartenir à un paiement de votre boutique. Le statut, le montant et l'ID de transaction proviennent toujours de la Transaction Status API de Hubtel. La commande n'est créée comme payée qu'après que cette API a confirmé le paiement et son montant.

Vérifications de paiement en arrière-plan (cron) : l'URL cron avec un jeton secret. Appelez-la toutes les 5 minutes depuis le cron de votre serveur, par exemple avec curl. Les paiements sans confirmation sont alors revérifiés automatiquement auprès de Hubtel : 20 minutes après l'envoi du client vers Hubtel, une fois de plus au bout d'une heure si le paiement est toujours impayé, et jusqu'à 5 fois avec des délais croissants lorsque Hubtel était injoignable. Gardez l'URL confidentielle.

Avancé

Debug log : enregistre les appels à l'API et les callbacks dans logs/hubtel_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les clés et les données clients ne sont pas enregistrées. Les erreurs et les avertissements sont toujours enregistrés, même si cette option est désactivée. Par défaut : désactivé.

Log : affiche la taille actuelle et les dernières entrées du journal. Cliquez sur Clear log pour le vider.

Delete data on uninstall : lorsqu'elle est activée, la désinstallation du module supprime les réglages et le journal de ce module. Les données Hubtel enregistrées pour les commandes et le statut de commande Hubtel payment on hold sont toujours conservés. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le mode de paiement (par défaut Mobile Money or card (Hubtel)) et valide. Le module crée un paiement Hubtel pour le total du panier en GHS et envoie le client sur la page de paiement de Hubtel. Le paiement y apparaît sous le nom Cart #, suivi du numéro de panier et du nom de votre boutique. Sur la page Hubtel, le client paie avec MTN MoMo, Telecel Cash, AirtelTigo Money, une carte Visa ou Mastercard ou GhQR. Aucune commande n'existe encore à ce stade. Chaque validation à l'étape de paiement crée une nouvelle tentative de paiement avec sa propre référence, et les anciennes pages Hubtel du même panier restent payables.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée comme payée qu'après confirmation par Hubtel via la Transaction Status API : par le callback, par la vérification effectuée au retour du client, par une vérification en arrière-plan ou par le bouton de la page de la commande. Un callback et un retour arrivant au même moment sont traités l'un après l'autre, si bien que la commande n'est jamais créée deux fois. Le client voit ensuite la page standard de confirmation de commande. Si la commande a été mise en attente, la page affiche Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.

Si Hubtel n'a pas encore confirmé le paiement au retour du client, une page Payment confirmation affiche 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. avec les boutons Check again et Back to checkout. La commande est créée dès que Hubtel confirme le paiement. Si Hubtel a déjà signalé cette tentative comme échouée, le client revient au paiement avec The Hubtel payment was not completed. You can try again or choose another payment method. Le panier est conservé.

Si le client clique sur Cancel sur la page Hubtel, le module vérifie d'abord si le paiement a tout de même été effectué. Si ce n'est pas le cas, le client revient au paiement avec The Hubtel payment was cancelled. You can try again or choose another payment method. Le panier est conservé. Un paiement ultérieur depuis la page Hubtel annulée reste accepté.

Si Hubtel ne peut pas démarrer le paiement, le client reste à l'étape de paiement avec un court message, par exemple 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. ou, avec des identifiants erronés, Hubtel payments are not available at the moment. Please choose another payment method. Les détails sont enregistrés dans le journal.

Le module ne prend en charge ni les remboursements depuis PrestaShop, ni les abonnements, ni les cartes enregistrées, ni le choix du canal de paiement dans la boutique.

Commandes

Statuts de commande

No order yet : le client a été envoyé vers Hubtel et n'a pas payé, ou Hubtel n'a pas encore confirmé le paiement. Seul le panier existe.

Payment accepted : le paiement a été confirmé pour le total exact du panier en GHS. Il est enregistré avec l'ID de transaction Hubtel, et une note indique le montant, la transaction Hubtel, le mode de paiement et la référence.

Hubtel payment on hold : Hubtel a signalé un montant payé différent du total du panier, ou le panier n'est pas en GHS. La commande n'a pas été marquée comme payée ; le montant réellement prélevé par Hubtel est enregistré comme paiement, et une note explique l'écart. Vérifiez le paiement dans le tableau de bord Hubtel, puis traitez la commande ou remboursez-la manuellement. Si une autre tentative du même panier est ensuite payée pour le bon montant, la commande passe à Payment accepted.

Si une autre tentative d'une commande déjà payée est aussi payée, la commande ne change pas. Une note vous demande de rembourser le doublon dans votre tableau de bord Hubtel. Un paiement pour une commande annulée ou remboursée ajoute une note, et la commande n'est jamais rouverte automatiquement. Lorsque Hubtel signale un paiement comme remboursé, une note est ajoutée à la commande.

Bloc de paiement Hubtel

La page de la commande affiche un bloc Hubtel payment avec toutes les tentatives de paiement du panier de la commande : date, référence, paiement Hubtel, montant, statut Hubtel, transaction et résultat. Sous les tentatives, il liste les Hubtel notes de la commande, de la plus récente à la plus ancienne.

Le bouton Check Hubtel payment status vérifie les dernières tentatives de la commande (jusqu'à 5, de la plus récente à la plus ancienne, en s'arrêtant dès que la commande est payée), applique le résultat et ajoute une note avec le statut de chaque tentative. Le résultat s'affiche dans le bloc. Vous avez besoin du droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. Le bouton est disponible dès que la commande existe. Un panier payé sans commande est confirmé par le callback, le retour du client ou le cron.

Remboursements

Les remboursements depuis PrestaShop ne sont pas pris en charge. Remboursez le paiement dans le tableau de bord Hubtel, puis enregistrez le remboursement dans PrestaShop. Les boutons de remboursement standard de PrestaShop sur la page de la commande ne renvoient pas d'argent via Hubtel.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Hubtel Pay Gateway est le premier bloc de la page Modules > Module Manager > VibeFox Hubtel Pay Gateway > Configure, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date jusqu'à laquelle la licence est active et votre domaine) ainsi que les boutons Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour retirer la clé de cette boutique. En dessous figurent la ligne Product: presta-payment-hubtel et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de l'autorisation Configure pour le module peuvent modifier la clé. Les textes du bloc suivent la langue du back office (l'anglais et le russe sont inclus).

Si la clé n'est pas acceptée, le bloc indique la raison, par exemple Key not found, This key belongs to another product, Domain limit reached ou License expired on suivi d'une date. Après un changement d'adresse de la boutique, ou après avoir libéré un emplacement de domaine dans votre compte, cliquez sur Check now. Si le serveur de licences est injoignable, le module continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine : celui de la boutique principale, y compris dans une configuration multiboutique. Retirer la clé de la boutique ne libère pas son emplacement de domaine. Libérez l'emplacement dans votre compte vibefox.net.

Sans clé active, Hubtel n'est pas proposé aux clients au moment du paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. La boutique PrestaShop ne sait pas que vous êtes connecté au back office, donc le mode de paiement est masqué aussi pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au moment du paiement. Un rappel apparaît dans Modules > Module Manager, sur l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés continuent d'être confirmés également par les vérifications de paiement en arrière-plan.

Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement pendant que vous travaillez dans le back office : une fois par jour pendant les 14 premiers jours après la saisie de la clé, puis une fois par semaine. Aucune tâche cron n'est nécessaire pour la vérification de la licence. La désinstallation ou la réinitialisation du module supprime toujours la clé de licence et le statut de licence.

Dépannage

Hubtel n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable/Disable est activé, que l'API ID, l'API Key et le numéro de compte marchand sont renseignés et que la devise du panier est GHS. Dans Payment > Preferences, vérifiez que le module est autorisé pour GHS, le pays du client et le groupe du client. La page des réglages affiche un avertissement lorsque les identifiants ou la devise sont incorrects.

Le paiement a été effectué, mais aucune commande n'a été créée : le paiement n'a pas pu être confirmé. Activez Debug log et consultez le champ Log sur la page du module. Une erreur HTTP 401 ou 403 lors de la vérification du statut signifie que les clés d'API sont incorrectes ou que l'IP du serveur n'est pas inscrite sur liste blanche par Hubtel. Vérifiez aussi que l'URL de callback est accessible depuis Internet et que l'URL cron est appelée. Dès que Hubtel répond, le prochain callback, la prochaine vérification en arrière-plan ou le prochain retour du client crée la commande.

Le callback répond Unknown reference : la référence du paiement n'appartient à aucun paiement de cette boutique.

Le callback répond Payment status unavailable : la Transaction Status API était injoignable ou a refusé la requête, ou le panier était en cours de confirmation par une autre requête au même moment. Le paiement est revérifié en arrière-plan après 5 minutes.

Le callback répond Gateway not configured : l'API ID, l'API Key ou le numéro de compte marchand est manquant. Renseignez-les ; le paiement est revérifié en arrière-plan.

Le callback répond Invalid request ou Invalid ClientReference : la requête ne contenait pas un callback Hubtel valide.

L'URL de callback affiche Method not allowed dans le navigateur : c'est normal. L'URL n'accepte que les requêtes provenant de Hubtel.

L'URL cron répond Forbidden : le jeton dans l'URL est incorrect. Copiez l'URL cron exactement telle qu'elle apparaît dans les réglages.

La commande est Hubtel payment on hold : lisez les notes du bloc Hubtel payment (voir Statuts de commande), vérifiez le paiement dans le tableau de bord Hubtel, puis traitez la commande ou remboursez-la manuellement.

Le client voit une erreur en choisissant Hubtel : activez Debug log et consultez le journal. Des clés d'API incorrectes donnent Hubtel payments are not available at the moment. Un problème de connexion donne Could not connect to Hubtel. Un panier dans une autre devise donne Hubtel accepts payments in Ghana cedis (GHS) only. Please choose another payment method.

Pour les développeurs : le hook actionWcpHubtelPayIcon modifie l'icône du mode de paiement, et actionWcpHubtelPayPaymentDescription modifie la description du paiement sur la page Hubtel (100 caractères maximum).

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Hubtel Pay Gateway et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete data on uninstall est activé, les réglages et le journal de ce module sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une réinstallation ultérieure. Les données Hubtel enregistrées pour les commandes et le statut de commande Hubtel payment on hold sont toujours conservés. Les commandes existantes gardent leurs notes de paiement et leurs ID de transaction.

Hubtel est une marque de son propriétaire respectif. Ce module n'est ni affilié à Hubtel ni approuvé par Hubtel.