VibeFox HyperPay for WooCommerce — Aide
Prérequis
WordPress: 6.0 ou ultérieur.
WooCommerce: 8.0 ou ultérieur, installé et actif. Le plugin refuse de s'activer sans lui.
PHP: 8.0 ou ultérieur.
Compte HyperPay : HyperPay vous fournit l'Access Token et l'Entity ID lors de la création de votre compte marchand. Les identifiants de test et de production sont différents. Il vous faut aussi un webhook de paiement dans le tableau de bord HyperPay et sa clé de déchiffrement (clé du webhook), affichée sous Administration > Webhooks (voir Configuration).
Données de carte : la carte n'est saisie que dans le widget HyperPay ; les données de carte n'atteignent donc jamais votre serveur (PCI DSS SAQ A).
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 du plugin et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier wcp_hyperpay_payment_gateway dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Payments > HyperPay > Manage, ou cliquez sur Settings sous le nom du plugin sur la page Plugins.
4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.
5. Saisissez l'Access Token, l'Entity ID et la clé de webhook de test fournis par HyperPay, et laissez Test Mode activé.
6. Dans le tableau de bord HyperPay (Administration > Webhooks), ajoutez un webhook de paiement avec l'URL affichée dans les réglages, puis copiez sa clé de déchiffrement dans le champ de clé du webhook du même mode.
7. Activez Enable/Disable et effectuez un paiement de test avec une carte de test HyperPay. Saisissez ensuite les identifiants de production et désactivez Test Mode.
Configuration
Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > HyperPay. Au-dessus des champs, la page affiche Le mode test est activé : les paiements sont envoyés au système de test de HyperPay et aucun argent réel n'est débité. tant que le mode test est activé. Elle vous alerte lorsque l'Access Token ou l'Entity ID du mode actuel manque (le mode de paiement n'est alors pas proposé lors du paiement), et lorsque le mode actuel n'a pas de clé de webhook valide (les paiements ne sont alors confirmés que lorsque le client revient dans la boutique). Dans la liste des modes de paiement, la passerelle est signalée comme nécessitant une configuration tant que le mode actuel n'a pas son Access Token et son Entity ID. À l'enregistrement, les espaces sont supprimés des identifiants, et la page affiche une erreur si une clé de webhook n'est pas une clé hexadécimale de 64 caractères.
Enable/Disable: Enable HyperPay Payment active ou désactive le mode de paiement. Par défaut : désactivé.
Title: le titre que voit le client lors du paiement. Par défaut : Credit/Debit Card (HyperPay).
Description: la description que voit le client lors du paiement. Par défaut : Pay securely using your credit or debit card.
Identifiants API
L'Access Token, l'Entity ID et la clé de webhook sont fournis par HyperPay lors de la création de votre compte marchand. Les identifiants de test et de production sont différents. La clé de webhook s'affiche dans le tableau de bord HyperPay, sous Administration > Webhooks.
Test Mode: Enable Test Mode utilise le système de test de HyperPay (eu-test.oppwa.com) et les identifiants de test. Aucun argent réel n'est débité. Désactivez-le pour accepter de vrais paiements avec les identifiants de production (eu-prod.oppwa.com). Par défaut : activé.
Test Access Token: le jeton porteur de votre compte de test HyperPay.
Test Entity ID: l'Entity ID du canal de paiement de test.
Test Webhook Key: la clé hexadécimale de 64 caractères utilisée pour déchiffrer les notifications de webhook du système de test.
Live Access Token: le jeton porteur de votre compte HyperPay de production.
Live Entity ID: l'Entity ID du canal de paiement de production.
Live Webhook Key: la clé hexadécimale de 64 caractères utilisée pour déchiffrer les notifications de webhook du système de production.
Webhook
Le webhook informe votre boutique des paiements même lorsque le client ferme son navigateur avant de revenir dans la boutique. Dans le tableau de bord HyperPay (Administration > Webhooks), ajoutez un webhook pour les paiements avec l'URL affichée dans cette section des réglages. Elle ressemble à https://your-site/wp-json/hyperpay-p/v1/webhook. Copiez ensuite la clé de déchiffrement du webhook dans Test Webhook Key ou Live Webhook Key, selon le mode.
Les webhooks HyperPay sont chiffrés (AES-256-GCM). Un webhook qui ne peut pas être déchiffré avec vos clés est rejeté. Seules les notifications de paiement sont traitées, et le paiement doit appartenir à une session de paiement d'une de vos commandes, créée dans le même mode que la clé qui l'a déchiffré. Les notifications de test de HyperPay sont accusées de réception. Le webhook signale aussi les captures, reversements, remboursements et litiges (chargebacks) effectués dans le tableau de bord HyperPay (voir Commandes et remboursements). Sans webhook, un paiement n'est confirmé que lorsque le client revient dans la boutique après avoir payé.
Paiement
Transaction Type: le mode de débit de la carte.
Payment Brands: les marques affichées dans le widget de paiement : VISA, Mastercard, mada, American Express, STC Pay, Apple Pay. Par défaut : VISA et Mastercard. Ne sélectionnez que les marques que HyperPay a activées pour votre Entity ID ; mada, STC Pay et Apple Pay utilisent souvent leur propre entité, que ce plugin ne prend pas en charge.
Avancé
Enable Logging: Log API requests and responses. Les informations de débogage sont écrites dans WooCommerce > Status > Logs, source wcp_hyperpay_payment_gateway. Les erreurs sont toujours journalisées. Les journaux ne contiennent aucune donnée de carte, clé ni donnée client. Par défaut : désactivé.
Delete Data on Uninstall: Delete all plugin data when the plugin is uninstalled. Supprime les réglages et les fichiers journaux lors de la suppression du plugin. Les données HyperPay enregistrées sur les commandes sont conservées. Par défaut : désactivé.
Paiement
Le client choisit le mode de paiement (par défaut Credit/Debit Card (HyperPay)) et clique sur Continue to payment. La commande est créée et le client accède à la page Pay for order. Le plugin y prépare une session de paiement HyperPay pour le total de la commande dans la devise de la commande, et affiche le widget HyperPay avec le message Veuillez finaliser votre paiement ci-dessous :. Le widget utilise la langue de votre site lorsque HyperPay la prend en charge. En mode test, la page affiche Mode test : utilisez une carte de test HyperPay, aucun paiement réel ne sera effectué. Le client saisit les données de sa carte dans le widget.
Après le paiement, le client revient dans votre boutique. Le plugin vérifie que le paiement appartient à l'une des sessions de paiement de cette commande et demande à HyperPay le résultat au moyen d'une requête serveur à serveur. La commande n'est marquée payée qu'après confirmation de HyperPay : par cette requête ou par le webhook. Le montant et la devise doivent correspondre à la commande. Un retour et un webhook arrivant au même moment sont traités l'un après l'autre, de sorte que la commande n'est jamais traitée deux fois. Une fois le paiement confirmé, le client arrive sur la page de commande reçue.
Si le paiement n'a pas abouti, le client revient sur la page Pay for order avec un message : Échec du paiement : suivi du motif communiqué par HyperPay, Le paiement n'a pas été finalisé. Veuillez réessayer., ou Nous n'avons pas encore pu confirmer votre paiement. Si vous avez été débité, la commande sera mise à jour automatiquement ; sinon, veuillez réessayer. Le client peut payer à nouveau sur la même page. Si le widget ne peut pas être préparé, le client voit un bref message, par exemple indiquant que certaines données de facturation n'ont pas été acceptées par le prestataire de paiement, ainsi qu'un bouton Try Again. Les détails sont ajoutés aux notes de commande.
Les montants sont transmis avec deux décimales, comme l'exige l'API HyperPay. Pour les devises à 3 décimales (KWD, BHD, JOD, OMR), le total de la commande est arrondi à deux décimales.
Le mode de paiement fonctionne sur le paiement classique, sur les blocs Panier et Paiement, ainsi que sur la page Pay for order. En mode test, le bloc Paiement affiche Mode test : aucun paiement réel ne sera effectué. Il est compatible avec le stockage haute performance des commandes de WooCommerce (HPOS).
L'extension ne gère ni remboursements ni annulations depuis WooCommerce, ni cartes enregistrées ou tokenisation, ni abonnements, ni vérification de domaine Apple Pay, ni entité distincte par marque, ni Tabby, Tamara ni autres solutions de paiement en plusieurs fois (buy-now-pay-later).
Commandes et remboursements
Statuts de commande
Pending payment: le client n'a pas encore payé, n'a pas terminé le widget, ou HyperPay n'a pas encore confirmé le paiement.
Processing: un paiement par débit a été confirmé, ou une préautorisation a été capturée. Les commandes ne comportant que des produits téléchargeables virtuels passent à Terminée, le statut par défaut de WooCommerce. La note de commande indique le code de résultat HyperPay, sa description et l'ID de paiement. L'ID de transaction est l'ID de paiement HyperPay. Si HyperPay a signalé le paiement pour examen manuel, la note le précise ; vérifiez-le dans le tableau de bord HyperPay avant l'expédition.
On hold (pre-authorization): le montant a été réservé. Capturez-le avec l'action de commande Capture HyperPay payment ou dans le tableau de bord HyperPay ; le webhook de capture finalisera alors la commande.
On hold after payment: HyperPay a signalé un montant ou une devise différent de ceux de la commande (par exemple parce que la commande a été modifiée après l'ouverture de la page de paiement), le paiement est toujours en attente chez HyperPay, ou le paiement est arrivé après l'annulation de la commande. La note de commande l'explique. Vérifiez le paiement dans le tableau de bord HyperPay, puis finalisez-le ou remboursez-le.
Failed: HyperPay a refusé le paiement. Le motif figure dans la note de commande et est affiché au client. Une tentative refusée ne modifie jamais une commande déjà payée, réservée, en attente ou annulée.
Cancelled: une préautorisation a été annulée dans le tableau de bord HyperPay, et le webhook d'annulation annule la commande en attente.
Si un autre paiement réussi arrive pour une commande déjà payée, la commande n'est pas modifiée. Une note vous invite à rembourser le doublon dans le tableau de bord HyperPay. Un paiement réussi pour une commande remboursée ajoute seulement une note.
Capture
L'action de commande Capture HyperPay payment apparaît sur les commandes en attente avec une préautorisation non encore capturée. Elle capture le total actuel de la commande, diminué des remboursements déjà enregistrés dans WooCommerce, dans le mode où la préautorisation a été effectuée. Après une capture réussie, la commande passe à En cours. Si HyperPay refuse la capture, le code de résultat et la description sont affichés et ajoutés aux notes de commande. L'annulation (void) d'une préautorisation se fait dans le tableau de bord HyperPay.
Remboursements
Les remboursements depuis WooCommerce ne sont pas pris en charge. Remboursez le paiement dans le tableau de bord HyperPay, puis enregistrez-le dans WooCommerce avec Refund manually. Les remboursements et litiges (chargebacks) effectués dans HyperPay sont ajoutés à la commande comme note par le webhook ; le statut de la commande n'est pas modifié.
Clé de licence
Le plugin fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > HyperPay. Collez la clé dans License key puis cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, ainsi que 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 vibefox.net.
Une clé fonctionne sur un seul domaine. Retirer la clé d'un site ne libère pas l'emplacement de son domaine. Libérez-le depuis votre compte vibefox.net.
Sans clé active, HyperPay n'est pas affiché aux clients lors du paiement. Si un paiement est tout de même lancé, le client voit Ce mode de paiement n'est pas disponible. Veuillez en choisir un autre. Les gestionnaires de la boutique connectés voient toujours le mode de paiement, marqué (unlicensed — visible to admins only), afin de pouvoir configurer et tester le plugin 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 sont toujours confirmés, et les captures fonctionnent.
Lorsqu'une licence expire, le plugin continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.
Dépannage
HyperPay n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que le mode actuel dispose de son Access Token et de son Entity ID : les identifiants de test en mode test, les identifiants de production en mode production. La page des réglages affiche un avertissement lorsqu'ils manquent.
Le paiement a abouti, mais la commande reste au statut Pending payment : le webhook ne fonctionne pas et le client n'est pas revenu dans la boutique. Dans le tableau de bord HyperPay, vérifiez que le webhook de paiement existe pour le mode utilisé, que son URL correspond exactement à celle affichée dans les réglages, et que sa clé de déchiffrement se trouve dans le champ de clé du webhook du même mode. Consultez WooCommerce > Status > Logs, source wcp_hyperpay_payment_gateway.
Le webhook répond Decryption failed: la clé du webhook appartient à un autre webhook ou à un autre mode. Recopiez la clé depuis le tableau de bord HyperPay.
Le webhook répond Webhook key not configured: aucune clé de webhook valide n'est définie. Saisissez la clé de 64 caractères dans les réglages. HyperPay renouvelle la tentative du webhook.
Le journal affiche Webhook ignored : le paiement n'appartient pas à une commande de cette boutique, ou il a été effectué dans l'autre mode. Les paiements de test et de production restent séparés.
Le formulaire de paiement ne se charge pas : lisez la note de commande. Une erreur de configuration signifie généralement un Access Token ou un Entity ID incorrect pour le mode actuel. Un message concernant les données de facturation signifie que HyperPay n'a pas accepté certaines données du client. Vérifiez que les Payment Brands sélectionnées sont activées pour votre Entity ID.
La commande est On hold avec une note de montant ou de devise non concordant : HyperPay a signalé un paiement qui ne correspond pas au total ou à la devise de la commande, par exemple parce que la commande a été modifiée après l'ouverture de la page de paiement. Vérifiez le paiement dans le tableau de bord HyperPay, puis finalisez-le ou remboursez-le.
La capture échoue : lisez le code de résultat et la description dans la note de commande. La capture est envoyée dans le mode de la préautorisation : les identifiants de ce mode doivent donc être configurés.
Le bloc de licence affiche une erreur : suivez le 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 injoignable, le plugin continue de fonctionner avec le dernier statut connu.
Pour les développeurs : le filtre hyperpay_p_icon modifie l'icône du mode de paiement.
Désinstallation
Désactiver le plugin conserve toutes les données. Pour le supprimer, désactivez-le puis supprimez-le depuis la page Plugins. La clé de licence et le statut de licence de ce plugin sont toujours supprimés. Les réglages de la passerelle, les données temporaires du plugin et les fichiers journaux ne sont supprimés que si Delete Data on Uninstall était activé. Sinon, ils sont conservés pour une future réinstallation. Les données HyperPay enregistrées sur les commandes sont toujours conservées. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.
HyperPay est une marque déposée de son titulaire respectif. Ce plugin n'est ni affilié à HyperPay ni approuvé par HyperPay.