VibeFox Hubtel for WooCommerce — Aide

Prérequis

WordPress : 6.2 ou ultérieur.

WooCommerce : 8.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Devise : cedi ghanéen (GHS) uniquement. Le moyen de paiement est masqué au paiement pour les autres devises. Conservez le nombre de décimales de WooCommerce réglé sur 2, car Hubtel facture en 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 d'adresses IP : Hubtel ne répond à sa Transaction Status API qu'à partir d'adresses IP de serveurs inscrites sur liste blanche. Demandez à Hubtel (votre responsable 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 les commandes restent En attente de paiement.

Aucun environnement de test : Hubtel n'a aucun sandbox public. Tous les paiements sont réels.

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

Installation

1. Dans WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi téléverser le dossier wcp_hubtel_pay dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Hubtel > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page Extensions.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

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

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

7. Activez Enable/Disable. L'URL de callback est transmise à Hubtel à chaque paiement, il n'y a donc rien à configurer dans le tableau de bord Hubtel.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Hubtel. Au-dessus des champs, la page vous avertit lorsque l'API ID, l'API Key ou le numéro de compte marchand manque, et lorsque la devise de la boutique n'est pas GHS. Dans les deux cas, Hubtel est masqué au paiement. Elle vous avertit également lorsque la boutique utilise plus de 2 décimales. Dans la liste des moyens de paiement, la passerelle est indiquée comme devant être configurée tant que les identifiants ne sont pas renseignés.

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

Title: le nom du moyen de paiement que voit le client au paiement. Par défaut : Mobile Money or card (Hubtel).

Description: le texte affiché sous le moyen de paiement au paiement. Par défaut : Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. You will be redirected to Hubtel to complete the payment.

Identifiants 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 également l'avis relatif à la liste blanche d'adresses 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 secrète.

Merchant account number (POS Sales ID): les paiements sont encaissés sur ce compte Hubtel et vérifiés par rapport à celui-ci.

Confirmation du paiement

Le callback informe votre boutique qu'un paiement a été effectué. L'URL de callback affichée dans cette section est envoyée à Hubtel avec chaque paiement, il n'y a donc rien à configurer dans le tableau de bord Hubtel. Elle ressemble à https://your-site/wc-api/hubtel_pay/. Elle doit être accessible depuis Internet : aucun mode de maintenance, aucune protection par mot de passe et aucun pare-feu ne doit bloquer Hubtel.

Les callbacks de Hubtel ne sont pas signés. L'extension ne récupère du callback que la référence de paiement ; cette référence doit appartenir à une commande de votre boutique. Le statut, le montant et l'identifiant de transaction proviennent toujours de la Transaction Status API de Hubtel. La commande n'est marquée payée qu'une fois que cette API a confirmé le paiement et son montant. Si Hubtel ne peut pas être contacté, le paiement est revérifié automatiquement en arrière-plan, et vous pouvez le contrôler depuis l'écran de la commande via Order actions > Check Hubtel payment status.

Avancé

Debug log: Log API calls and callbacks dans WooCommerce > Status > Logs, source wcp_hubtel_pay, sans clés ni données clients. Les erreurs sont toujours journalisées. Par défaut : désactivé.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Hubtel data saved on orders is kept). Par défaut : désactivé.

Paiement

Le client choisit le moyen de paiement (par défaut Mobile Money or card (Hubtel)) et passe la commande. L'extension crée un paiement Hubtel pour le montant total de la commande en GHS et redirige le client vers la page de paiement Hubtel. Le paiement y apparaît avec Order #, le numéro de commande et le nom de votre site. Sur la page Hubtel, le client règle par MTN MoMo, Telecel Cash, AirtelTigo Money, carte Visa ou Mastercard, ou GhQR. Chaque clic sur Place order ou Pay crée une nouvelle tentative de paiement avec sa propre référence, et les anciennes pages Hubtel d'une même commande restent payables.

Après le paiement, le client revient sur la page de confirmation de commande. La commande n'est marquée payée qu'après confirmation par Hubtel via sa 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 l'action de commande. Un callback et un retour arrivant au même instant sont traités l'un après l'autre, de sorte que la commande n'est jamais complétée deux fois. Si Hubtel n'a pas encore confirmé le paiement, la page 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. Si la commande a été mise en attente, elle affiche Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.

Si le client clique sur Cancel sur la page Hubtel, l'extension vérifie d'abord si le paiement a été effectué malgré tout. Si ce n'est pas le cas, le client retourne sur la page Pay for order avec le message The Hubtel payment was cancelled. You can try again or choose another payment method.

Si Hubtel ne parvient pas à initialiser le paiement, le client voit 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, en cas d'identifiants incorrects, Hubtel payments are not available at the moment. Please choose another payment method. Les détails sont enregistrés dans le journal.

Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est compatible avec le stockage des commandes haute performance (HPOS) de WooCommerce.

L'extension ne propose pas de remboursement depuis WooCommerce, ni d'abonnement, ni d'enregistrement de cartes, ni de choix du canal de paiement dans WooCommerce.

Commandes

Statuts de commande

Pending payment: le client a été redirigé vers Hubtel et n'a pas encore payé, ou Hubtel n'a pas encore confirmé le paiement.

Processing: le paiement a été confirmé. Les commandes contenant uniquement des produits virtuels téléchargeables passent à l'état Terminée, le comportement par défaut de WooCommerce. La note de commande indique le montant, la transaction Hubtel, le moyen de paiement et la référence. L'identifiant de transaction correspond à l'identifiant de transaction Hubtel.

On hold: Hubtel a signalé un montant payé qui diffère du total de la commande, ou la commande n'est pas en GHS (note Hubtel amount/currency mismatch) ; ou un paiement est arrivé pour une commande qui avait été annulée. La commande n'a pas été marquée comme payée. Vérifiez le paiement dans le tableau de bord Hubtel et complétez ou remboursez la commande manuellement.

Failed: Hubtel a signalé que la dernière tentative de paiement d'une commande en attente de paiement a échoué, et la Transaction Status API confirme qu'elle n'est pas payée. Le client peut réessayer depuis la commande. Un échec signalé uniquement par un callback ne fait jamais échouer une commande.

Si une autre tentative d'une commande déjà payée est également payée, la commande n'est pas modifiée. Une note vous invite à rembourser le doublon dans votre tableau de bord Hubtel. Une commande annulée ou remboursée n'est jamais rouverte automatiquement. Lorsque Hubtel signale un paiement comme remboursé, une note est ajoutée à la commande.

Vérifications du paiement

Environ 20 minutes après la redirection du client vers Hubtel, une vérification en arrière-plan (WooCommerce Action Scheduler) interroge Hubtel sur le statut du paiement, au cas où le callback aurait été perdu et que le client ne soit pas revenu. Une tentative impayée est contrôlée une fois de plus au bout d'une heure. Lorsque l'API Hubtel ne peut pas être jointe, la vérification est répétée jusqu'à 5 fois avec des délais croissants.

L'action de commande Check Hubtel payment status vérifie les dernières tentatives de la commande (jusqu'à 5, de la plus récente à la plus ancienne), applique le résultat et ajoute une note avec le statut de chaque tentative.

Remboursements

Les remboursements depuis WooCommerce ne sont pas pris en charge. Effectuez le remboursement dans le tableau de bord Hubtel, puis saisissez un remboursement manuel dans WooCommerce.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > Hubtel. Collez la clé dans License key et cliquez sur Activate. Le bloc indique le statut, par exemple la date jusqu'à laquelle la licence est valide et votre domaine. Utilisez Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte sur vibefox.net.

Une clé fonctionne sur un seul domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez l'emplacement dans votre compte sur vibefox.net.

Sans clé active, Hubtel n'est pas proposé aux clients au paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. Les gestionnaires de la boutique connectés voient toujours le moyen de paiement, marqué comme (unlicensed — visible to admins only), ce qui vous permet de configurer et de tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Extensions et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées : les paiements déjà lancés continuent d'être confirmés.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est à nouveau vérifié automatiquement en arrière-plan.

Dépannage

Hubtel n'apparaît pas au 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 est bien le GHS. Sur la page Pay for order, c'est la devise de la commande qui compte. La page des réglages affiche un avertissement si les identifiants ou la devise sont incorrects.

Le paiement a été effectué, mais la commande reste En attente de paiement : le paiement n'a pas pu être confirmé. Ouvrez WooCommerce > Status > Logs, source wcp_hubtel_pay. Un code HTTP 401 ou 403 lors du contrôle de 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 également que l'URL de callback est accessible depuis Internet. Après correction, ouvrez la commande et exécutez Order actions > Check Hubtel payment status. Les vérifications en arrière-plan confirment également la commande dès que Hubtel répond.

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

Le callback répond Payment status unavailable : la Transaction Status API n'a pas pu être jointe ou a refusé la requête. Le paiement est revérifié en arrière-plan.

La commande est en attente avec une note de non-concordance de montant ou de devise : Hubtel a signalé un montant payé différent du total de la commande, ou la commande n'est pas en GHS. Vérifiez le paiement dans le tableau de bord Hubtel et complétez ou remboursez la commande manuellement.

Le client voit une erreur lors du passage de commande : activez Debug log et consultez le journal. Des clés d'API incorrectes affichent Hubtel payments are not available at the moment. Un problème de connexion affiche Could not connect to Hubtel.

Le bloc de licence affiche une erreur : suivez les instructions du message affiché dans le bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est inaccessible, l'extension continue de fonctionner selon le dernier statut connu.

Pour les développeurs : le filtre hubtel_p_icon modifie l'icône du moyen de paiement, et hubtel_p_payment_description modifie la description du paiement sur la page Hubtel (jusqu'à 100 caractères).

Désinstallation

Lorsque vous désactivez l'extension, toutes les données sont conservées ; seules les vérifications de paiement en arrière-plan en attente sont annulées. Pour la supprimer, désactivez-la et supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension sont toujours supprimés. Les réglages de la passerelle, les options propres à l'extension, les vérifications en arrière-plan en attente et les journaux ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les données Hubtel enregistrées sur les commandes constituent l'historique des paiements et sont toujours conservées. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Hubtel est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à Hubtel ni approuvée par Hubtel.