VibeFox HyperPay for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur avec l'extension OpenSSL (elle déchiffre les webhooks). Sans elle, le module ne peut pas être installé.

Compte HyperPay : HyperPay 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. Vous avez aussi besoin d'un webhook de paiement dans le tableau de bord HyperPay et de sa clé de déchiffrement (webhook key), affichée sous Administration > Webhooks (voir Configuration).

Données de carte : la carte n'est saisie que dans le widget HyperPay, de sorte que les données de carte n'atteignent 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 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 HyperPay Payment Gateway dans la liste des modules et cliquez sur Configure.

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

4. Saisissez l'Access Token, l'Entity ID et la clé de webhook de test fournis par HyperPay, et laissez Test Mode activé.

5. Dans le tableau de bord HyperPay (Administration > Webhooks), ajoutez un webhook de paiement avec l'URL affichée dans la section Webhook, puis copiez sa clé de déchiffrement dans le champ de clé de webhook du même mode.

6. Activez Enable/Disable, cliquez sur Save et effectuez un paiement de test avec une carte de test HyperPay. Saisissez ensuite les identifiants de production et désactivez Test Mode.

À l'installation, le module crée trois statuts de commande : Awaiting HyperPay payment, HyperPay payment authorized et HyperPay payment on hold. PrestaShop associe un nouveau module de paiement aux devises, pays et groupes de clients actifs à ce moment-là. Les pays que vous activez plus tard doivent être autorisés dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox HyperPay Payment Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche Test mode is on: payments go to the HyperPay test system and no real money is charged. tant que le mode test est activé. Elle vous avertit lorsque l'Access Token ou l'Entity ID du mode actuel est absent (le moyen de paiement n'est alors pas proposé dans le tunnel de commande), 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). À l'enregistrement, les espaces sont supprimés des identifiants, et la page vous avertit si une clé de webhook n'est pas une clé hexadécimale de 64 caractères.

HyperPay

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

Title : le titre que le client voit dans le tunnel de commande. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Credit/Debit Card (HyperPay). Obligatoire.

Description : la description que le client voit dans le tunnel de commande. 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 est affichée dans le tableau de bord HyperPay, sous Administration > Webhooks.

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é. Tant qu'il est activé, les clients voient Test mode: no real payment will be made. sous le moyen de paiement.

Test Access Token : le jeton d'accès (bearer token) 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 d'accès (bearer token) 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.

Les access tokens et clés de webhook enregistrés ne sont jamais réaffichés. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.

Effacer les secrets enregistrés : cochez un jeton ou une clé et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

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 sous Webhook URL dans cette section. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_hyperpay_payment_gateway/webhook, éventuellement avec un code de langue comme /en/. Copiez l'URL exactement telle qu'elle est affichée dans les réglages. Copiez ensuite la clé de déchiffrement du webhook dans Test Webhook Key ou Live Webhook Key, pour le même 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 de l'un de vos paniers, créée dans le même mode que la clé qui l'a déchiffré. Les notifications de test de HyperPay sont acquittées. Le webhook signale aussi les captures, annulations, remboursements et rétrofacturations 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é.

Payment

Transaction Type : la manière dont la carte est débitée.

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. Si aucune marque n'est cochée, la page vous avertit et le widget affiche VISA et Mastercard. Sélectionnez uniquement les marques que HyperPay a activées pour votre Entity ID ; mada, STC Pay et Apple Pay utilisent souvent leur propre entité, que ce module ne prend pas en charge.

Advanced

Enable Logging : consigne les requêtes et réponses de l'API dans logs/hyperpay_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements sont toujours consignés. Les journaux ne contiennent aucune donnée de carte, clé ni donnée client. Par défaut : désactivé.

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

Delete Data on Uninstall : lorsqu'il est activé, la désinstallation du module supprime les réglages, la table des tentatives de paiement HyperPay et les fichiers journaux. Les commandes et les statuts de commande du module sont conservés. Par défaut : désactivé.

Tunnel de commande

À l'étape de paiement, le client choisit le moyen de paiement (par défaut, Credit/Debit Card (HyperPay)) et confirme la commande. Le module prépare une session de paiement HyperPay pour le total du panier, dans la devise du panier, et ouvre la page HyperPay payment de votre boutique avec le widget HyperPay et le message Please complete your payment below:. Le widget utilise la langue du client lorsque HyperPay la prend en charge. En mode test, la page affiche Test mode: use a HyperPay test card, no real payment will be made. Le client saisit les données de sa carte dans le widget, ou suit Choose another payment method pour revenir au tunnel de commande. À ce stade, aucune commande n'existe encore. Recharger la page réutilise la même session de paiement pendant 25 minutes au maximum, tant que le panier ne change pas.

Après le paiement, le client revient dans votre boutique. Le module vérifie que le paiement appartient à l'une des sessions de paiement de ce panier et demande le résultat à HyperPay par une requête serveur à serveur, dans le mode où la session a été créée. La commande n'est marquée payée qu'une fois HyperPay le confirme : par cette requête ou par le webhook. Le montant et la devise doivent correspondre à ceux du panier. Si le retour et un webhook arrivent au même moment, ils sont traités l'un après l'autre, de sorte que la commande n'est jamais créée deux fois. Lorsque le paiement est confirmé, la commande est créée et le client voit la page standard de confirmation de commande.

Si le paiement n'a pas abouti, le client revient dans le tunnel de commande avec un message : Payment failed: suivi du motif donné par HyperPay, Payment was not completed. Please try again., ou We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. Le panier est conservé et le client peut payer à nouveau ; chaque nouvelle tentative reçoit une nouvelle session de paiement HyperPay. Si le formulaire de paiement ne peut pas être préparé, le client reste dans le tunnel de commande avec un bref message, par exemple indiquant que certaines données de facturation n'ont pas été acceptées par le prestataire de paiement, ou que le formulaire de paiement n'est pas disponible à cause d'une erreur de configuration du paiement. La raison technique est consignée dans le journal.

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 du panier est arrondi à deux décimales.

Le webhook fonctionne lorsque la boutique est en mode maintenance et n'est pas bloqué par la restriction de pays de votre boutique.

Le module ne gère ni remboursements ni annulations depuis PrestaShop, ni cartes enregistrées ou tokenisation, ni abonnements, ni vérification de domaine Apple Pay, ni entité distincte par marque, ni solutions de paiement en plusieurs fois (Tabby, Tamara ou autres buy-now-pay-later).

Commandes et remboursements

Statuts de commande

No order yet : le client a été envoyé sur la page de paiement et n'a pas payé, le paiement a été refusé, ou HyperPay n'a pas encore confirmé le paiement. Seul le panier existe.

Payment accepted : un paiement par débit a été confirmé, ou une préautorisation a été capturée. Le paiement est enregistré avec l'identifiant de paiement HyperPay comme identifiant de transaction, et une note privée affiche le code de résultat HyperPay, sa description et l'identifiant de paiement. Si HyperPay a signalé le paiement pour un examen manuel, la note l'indique ; vérifiez-le dans le tableau de bord HyperPay avant l'expédition.

HyperPay payment authorized : le montant a été réservé par une préautorisation. Capturez-le dans le bloc HyperPay de la commande ou dans le tableau de bord HyperPay ; le webhook de capture fait alors passer la commande à Payment accepted.

Awaiting HyperPay payment : HyperPay a signalé le paiement comme en attente. La commande passe à Payment accepted lorsque HyperPay le confirme.

HyperPay payment on hold : HyperPay a signalé un montant ou une devise différent de ceux du panier ou de la commande (par exemple, le panier a été modifié après l'ouverture de la page de paiement), ou le paiement est arrivé après l'annulation de la commande. La note l'explique. Vérifiez le paiement dans le tableau de bord HyperPay, puis traitez la commande ou remboursez le paiement.

Canceled : une préautorisation a été annulée dans le tableau de bord HyperPay, et le webhook d'annulation annule la commande autorisée.

Un résultat de refus ne modifie jamais une commande existante. Si un autre paiement réussi arrive pour une commande déjà payée, la commande n'est pas modifiée. Une note vous demande de rembourser le doublon dans le tableau de bord HyperPay. Un paiement réussi pour une commande remboursée ajoute seulement une note.

Bloc de paiement HyperPay

La page de commande affiche un bloc HyperPay payment avec l'identifiant de paiement (et l'identifiant de capture après une capture), le type de transaction, l'identifiant de la session de paiement, l'identifiant de transaction du marchand, le montant envoyé à HyperPay, le résultat et un badge Test mode pour les paiements de test. Les notes du module se trouvent dans les messages privés de la commande.

Capture

Pour une commande en HyperPay payment authorized, le bloc affiche Capture payment avec le montant. Cliquez dessus et confirmez Capture the pre-authorized amount through HyperPay?. Le total actuel de la commande est capturé, dans le mode où la préautorisation a été effectuée ; l'Access Token et l'Entity ID de ce mode doivent donc être renseignés. Vous devez avoir le droit de modifier les commandes ; l'accès aux pages du module n'est pas nécessaire. Après une capture réussie, la commande passe à Payment accepted et l'identifiant de capture est ajouté au paiement et aux notes. Si HyperPay refuse la capture, le code de résultat et la description sont affichés et ajoutés aux notes, et la commande reste autorisée. Un double clic ne capture pas deux fois. L'annulation (void) d'une préautorisation se fait dans le tableau de bord HyperPay.

Remboursements

Les remboursements depuis PrestaShop ne sont pas pris en charge, et les boutons de remboursement standard de PrestaShop ne renvoient pas d'argent via HyperPay. Remboursez le paiement dans le tableau de bord HyperPay et enregistrez-le dans PrestaShop avec un remboursement partiel ou un avoir si nécessaire. Les remboursements et rétrofacturations effectués dans HyperPay sont ajoutés à la commande sous forme de note par le webhook ; le statut de la commande ne change pas.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox HyperPay Payment Gateway est le premier bloc de Modules > Module Manager > VibeFox HyperPay Payment 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) et 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. Plus bas se trouvent la ligne Product: presta-payment-hyperpay 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, HyperPay n'est pas proposé aux clients dans le tunnel de commande. 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 : le moyen de paiement est donc masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester dans le tunnel de commande. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés, et les captures et remboursements fonctionnent.

Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié automatiquement pendant votre travail 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. La désinstallation ou la réinitialisation du module supprime toujours la clé de licence et le statut de licence.

Dépannage

HyperPay n'apparaît pas dans le tunnel de commande : 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 : ceux de test en mode test, ceux de production en mode production. La page des réglages affiche un avertissement s'ils manquent. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client.

Le paiement a abouti, mais aucune commande n'a été créée : 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 est exactement celle affichée sous Webhook URL, et que sa clé de déchiffrement se trouve dans le champ de clé de webhook du même mode. Activez Enable Logging et consultez le champ Log sur la page du module.

Le webhook répond Decryption failed : la clé de webhook appartient à un autre webhook ou à un autre mode. Copiez à nouveau 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. Collez la clé de 64 caractères dans les réglages. HyperPay relance le webhook.

Le webhook répond Busy, retry later : la commande était traitée par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple, parce que le module est désactivé). HyperPay relance le webhook. La raison figure dans le journal.

Le journal affiche Webhook ignored : le paiement n'appartient à aucun panier de cette boutique, ou il a été effectué dans l'autre mode. Les paiements de test et de production sont séparés.

L'URL du webhook affiche Method not allowed dans le navigateur : c'est normal. L'URL n'accepte que les requêtes POST émises par HyperPay.

Le formulaire de paiement ne se charge pas : consultez le journal. 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 en HyperPay payment on hold : lisez les notes de la commande (voir Statuts de commande), vérifiez le paiement dans le tableau de bord HyperPay, puis traitez la commande ou remboursez le paiement.

La capture échoue : lisez le code de résultat et la description dans le bloc et dans les notes. La capture est envoyée dans le mode de la préautorisation, dont les identifiants doivent donc être renseignés ; sinon, le bloc indique que l'Access Token / l'Entity ID de ce mode sont vides.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox HyperPay Payment Gateway et choisissez Uninstall. La clé de licence et le statut de la licence de ce module sont toujours supprimés. Si Delete Data on Uninstall est activé, les réglages, la table des tentatives de paiement HyperPay et les fichiers journaux sont supprimés. S'il est désactivé, tout est conservé pour une réinstallation ultérieure. Les statuts de commande Awaiting HyperPay payment, HyperPay payment authorized et HyperPay payment on hold sont toujours conservés. Les commandes existantes gardent leurs notes de paiement et leurs identifiants de transaction.

HyperPay est une marque déposée de son propriétaire respectif. Ce module n'est ni affilié à HyperPay ni approuvé par HyperPay.