VibeFox OpenPay for PrestaShop — Aide
Prérequis
PrestaShop : 8.0 à 9.x.
PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les anciennes versions de PHP.
HTTPS : votre boutique doit utiliser HTTPS, car le formulaire de carte se trouve sur votre page de paiement.
Compte OpenPay : un compte OpenPay du Mexique, de Colombie ou du Pérou. Vous avez besoin de son Merchant ID, de sa clé privée (sk_...) et de sa clé publique (pk_...). Les tableaux de bord sandbox et production ont des Merchant ID et des clés différents, et le module les garde séparés.
Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.
La carte est saisie sur votre page de paiement, mais elle est lue et tokenisée dans le navigateur par openpay.js. Les champs de carte n'ont pas de nom et ne sont jamais envoyés à votre serveur. Le formulaire de carte se trouvant sur votre page, votre périmètre PCI DSS est SAQ A-EP ; renseignez-vous auprès de votre acquéreur.
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éversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox OpenPay 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. Choisissez le Account country et saisissez les clés sandbox et production (voir Configuration).
5. Recommandé : ajoutez l'URL du webhook dans le tableau de bord OpenPay (voir Configuration).
6. Activez Enable / Disable et cliquez sur Save. Testez un paiement avec les cartes de test du sandbox OpenPay, puis désactivez Sandbox mode pour accepter de vrais paiements.
À l'installation, le module crée deux statuts de commande, Awaiting OpenPay payment et OpenPay payment on hold. PrestaShop propose un nouveau module de paiement pour les devises, les pays et les groupes de clients de votre boutique. Vous pouvez les limiter dans Payment > Preferences.
Configuration
Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox OpenPay Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit lorsque les clés du mode actuel sont incomplètes (le moyen de paiement est alors masqué à la caisse), lorsque la devise par défaut de votre boutique n'est pas acceptée par le pays de compte sélectionné, et affiche Sandbox mode is enabled — no real charges are made. tant que le mode sandbox est activé.
À l'enregistrement, les clés sont vérifiées. Un Merchant ID ne peut contenir que des lettres et des chiffres, une clé privée doit commencer par sk_ et une clé publique par pk_. Une valeur invalide n'est pas enregistrée : la valeur précédente est conservée et une erreur s'affiche, par exemple Sandbox: The private key must start with sk_. Si le moyen de paiement est activé mais que les clés du mode actuel sont incomplètes, un message indique également que la passerelle reste masquée à la caisse. Un Title vide est refusé avec Enter a title for the payment method.
OpenPay
Enable / Disable : Enable OpenPay card payments active ou désactive le moyen de paiement. Par défaut : désactivé.
Title : le nom du moyen de paiement que voient les clients à la caisse. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Credit or debit card (OpenPay). Obligatoire.
Description : le texte affiché au-dessus du formulaire de carte à la caisse. Par défaut : Pay securely with your credit or debit card. Your bank may ask you to confirm the payment (3D Secure).
Compte OpenPay
Le Merchant ID, la clé privée (sk_) et la clé publique (pk_) se trouvent dans votre tableau de bord OpenPay, sous Settings (Configuración). La section contient des liens vers les tableaux de bord sandbox et production du Mexique, de Colombie et du Pérou.
Account country : le pays de votre compte OpenPay. Il détermine l'API OpenPay, la bibliothèque openpay.js de ce pays et les devises acceptées. Par défaut : Mexico.
Sandbox mode : utilise le sandbox OpenPay (clés de test, aucun débit réel) et bascule à la fois les clés et l'API sur le sandbox. Un badge SANDBOX MODE s'affiche à la caisse tant qu'il est activé. Par défaut : activé. Désactivez-le pour accepter de vrais paiements.
Sandbox Merchant ID : le Merchant ID du tableau de bord sandbox, Settings (Configuración), clés API.
Sandbox Private Key : la clé privée sandbox. Elle commence par sk_. Elle n'est utilisée que sur le serveur ; ne la partagez jamais.
Sandbox Public Key : la clé publique sandbox. Elle commence par pk_. openpay.js l'utilise dans le navigateur pour tokeniser la carte.
Live Merchant ID : le Merchant ID du tableau de bord de production, Settings (Configuración), clés API.
Live Private Key : la clé privée de production (sk_...).
Live Public Key : la clé publique de production (pk_...).
Les clés privées enregistrées ne sont jamais réaffichées. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement si vous voulez la modifier.
Clear saved secrets : cochez une clé privée et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.
Webhook
Le webhook n'est pas obligatoire, mais recommandé. Il confirme les paiements lorsque le client ne revient pas de la page 3D Secure, par exemple après la fermeture du navigateur. Dans le tableau de bord OpenPay, allez dans Settings > Webhooks et ajoutez l'URL affichée dans Webhook URL dans cette section. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_openpay_gateway/webhook, éventuellement avec un code de langue comme /en/. Copiez-la exactement telle qu'elle apparaît dans les réglages. Ajoutez le webhook dans le tableau de bord de chaque mode utilisé (sandbox et production).
Lorsque vous ajoutez le webhook, OpenPay envoie un code de vérification à cette URL. Le code apparaît dans cette section avec la date de réception, afin que vous puissiez confirmer le webhook dans le tableau de bord OpenPay.
Sélectionnez ces événements (ils figurent aussi dans cette section) :
OpenPay ne signe pas les webhooks : le module ne fait donc jamais confiance à la notification elle-même. Il s'en sert uniquement pour retrouver le débit, puis lit le débit depuis l'API OpenPay avec la clé privée du mode et du pays de compte dans lesquels le paiement a été effectué. Une notification concernant un débit que cette boutique n'a pas créé est ignorée. Le webhook fonctionne lorsque la boutique est en mode maintenance et n'est pas bloqué par la restriction par pays de votre boutique.
Avancé
Debug log : enregistre les étapes du paiement dans logs/wc_opy_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements sont journalisés même lorsqu'il est désactivé. Les clés, les données de carte et les coordonnées du client ne sont jamais journalisées. 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 de la passerelle, le code de vérification du webhook enregistré et les journaux. Les enregistrements de débits OpenPay des commandes constituent l'historique des paiements et sont toujours conservés, afin que les commandes puissent encore être remboursées après une réinstallation. Par défaut : désactivé.
Paiement
À l'étape de paiement, le client choisit le moyen de paiement (par défaut Credit or debit card (OpenPay)) et renseigne Cardholder name, Card number, Expiry (MM/YY) et Card code (CVV). En mode sandbox, le formulaire affiche SANDBOX MODE — Test environment. No real charges will be made. Lorsque le client confirme, openpay.js transforme la carte en jeton à usage unique dans le navigateur, et la bibliothèque antifraude ajoute un identifiant de session d'appareil. Seules ces deux valeurs et le numéro du panier sont envoyées à votre boutique. Si le formulaire est incomplet, Please fill in all card fields. s'affiche sous le formulaire.
Le module crée alors le débit avec 3D Secure pour le total du panier dans la devise du panier, et envoie le client sur la page 3D Secure de sa banque, servie par OpenPay. Chaque tentative reçoit sa propre référence de commande OpenPay. La description du débit est Cart #, le numéro du panier et le nom de votre boutique. Le nom, l'e-mail et le téléphone du client sont transmis à OpenPay ; aucun compte client OpenPay n'est créé. Aucune commande n'existe encore à ce stade.
Lorsque le client revient, le module lit le débit depuis l'API OpenPay. La commande n'est marquée comme payée qu'après la confirmation d'OpenPay : le débit doit appartenir à ce panier, être terminé et correspondre exactement au total et à la devise du panier. La commande est alors créée et le client voit la page de confirmation de commande avec Your card payment has been received. Si OpenPay signale le débit comme étant en cours, la commande est créée dans Awaiting OpenPay payment et la page affiche We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. Si le résultat n'est pas encore connu, une page Payment confirmation affiche le même texte avec un bouton Check again et un bouton Back to checkout ; le webhook crée la commande dès son arrivée. Si un débit en cours échoue plus tard, la page de confirmation de commande affiche Your OpenPay card payment was not completed. Please contact us about this order.
Si la carte est refusée ou si 3D Secure échoue, le client revient à la caisse avec le message The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. et peut payer à nouveau. Le panier est conservé. Avant une nouvelle tentative, le module vérifie le débit précédent du panier : s'il a bien été payé, la commande est créée à partir de celui-ci sans second débit ; s'il est encore en cours, la commande est créée dans Awaiting OpenPay payment ; si son état ne peut pas être vérifié, aucun nouveau débit n'est effectué et le client voit We could not confirm the status of your previous payment attempt. Please try again in a few minutes. Un panier qui a déjà une commande n'est jamais débité à nouveau.
Les cartes refusées reçoivent un message clair, par exemple The card has insufficient funds. Please use another card., The card has expired. Please use another card. ou The security code (CVV) is not valid. Please check it and try again. Les erreurs techniques d'OpenPay ne sont jamais affichées aux clients ; elles sont envoyées au journal.
Si un bon de réduction du panier cesse d'être valable entre le paiement et sa confirmation, il est retiré de la commande. La commande passe alors en OpenPay payment on hold avec une note, car le client a payé le prix avec la réduction.
Le moyen de paiement est masqué à la caisse lorsqu'il est désactivé, lorsque les clés du mode actuel sont incomplètes ou lorsque la devise du panier n'est pas acceptée par le pays de compte.
Le module accepte uniquement les paiements par carte, avec capture immédiate. Il ne gère ni cartes enregistrées, ni abonnements, ni mensualités sans frais (MSI) ou paiements en plusieurs fois, ni paiements avec des points de carte, ni paiements en espèces, SPEI, PSE ou CoDi, ni autorisation et capture séparées.
Commandes et remboursements
Statuts de commande
Aucune commande pour l'instant : le client est sur la page 3D Secure, n'a pas terminé le paiement, ou la carte a été refusée. Seul le panier existe.
Payment accepted : le paiement a été confirmé. Il est enregistré avec l'ID du débit OpenPay comme ID de transaction, et une note indique l'ID du débit et le mode (production ou sandbox).
Awaiting OpenPay payment : OpenPay signale le débit comme étant en cours (pas encore capturé). La commande passe à Payment accepted lorsque le débit est terminé, ou à Payment error s'il échoue.
OpenPay payment on hold : OpenPay signale un débit terminé avec un montant ou une devise différent de ceux du panier (la commande n'est pas marquée comme payée, la note indique l'écart), un bon de réduction a été retiré, ou un paiement est arrivé pour une commande déjà annulée ou remboursée (le paiement est enregistré). Vérifiez la commande et traitez-la, ou remboursez le paiement dans le tableau de bord OpenPay.
Payment error : un débit en cours a échoué, a été annulé ou a expiré.
Refunded : le débit a été entièrement remboursé via le module.
Si un second débit terminé arrive pour une commande déjà payée, la commande n'est pas modifiée. Une note commençant par WARNING vous invite à rembourser le doublon dans le tableau de bord OpenPay.
Bloc de paiement OpenPay
La page de commande affiche un bloc OpenPay payment avec l'ID du débit, le statut du débit, l'environnement et le pays de compte, le montant débité et le total de la commande, le montant remboursé, un badge Sandbox pour les paiements sandbox, l'historique des remboursements et les OpenPay notes de la commande.
Remboursements
Pour les comptes du Mexique et du Pérou : dans le bloc OpenPay payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via OpenPay. Confirmez la question Refund this amount through OpenPay? This cannot be undone. Les remboursements totaux et partiels sont pris en charge, jusqu'au montant débité par OpenPay. Vous devez avoir le droit de modifier les commandes. Le remboursement est envoyé avec les clés du mode et du pays de compte dans lesquels le débit a été effectué ; ces clés doivent donc être renseignées : conservez les clés sandbox tant que vous pouvez encore rembourser des commandes sandbox. Si OpenPay n'accepte pas le remboursement, le bloc affiche l'erreur, par exemple OpenPay refund failed: ..., et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec l'ID de remboursement OpenPay. Un remboursement total fait passer la commande à Refunded. Un remboursement partiel ne modifie pas le statut. Les remboursements ne sont disponibles qu'une fois le paiement confirmé par OpenPay ; une commande mise en attente après un écart de montant n'est pas remboursée via le module.
OpenPay Colombie ne prend pas en charge les remboursements de cartes via l'API, comme dans les plugins officiels d'OpenPay. Pour les débits colombiens, le bloc n'offre pas de formulaire de remboursement ; remboursez le débit dans le tableau de bord OpenPay.
Le module ne crée pas d'avoirs. Les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d'argent via OpenPay.
Les remboursements et contestations effectués dans le tableau de bord OpenPay arrivent par webhook et sont ajoutés aux notes une seule fois. Le statut de la commande et les avoirs ne sont pas modifiés automatiquement. Mettez-les à jour manuellement si nécessaire.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox OpenPay Gateway est le premier bloc de Modules > Module Manager > VibeFox OpenPay 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 de fin de validité de la licence 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. En dessous figurent la ligne Product: presta-payment-openpay 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, OpenPay n'est pas affiché aux clients à la caisse. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. La vitrine 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 à la caisse. 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 sont toujours confirmés, et les 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é à 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. La désinstallation ou la réinitialisation du module supprime toujours la clé de licence et le statut de licence.
Dépannage
OpenPay n'apparaît pas à la caisse : vérifiez que la licence est active, que Enable / Disable est activé et que le mode actuel dispose des trois clés : les clés sandbox en mode sandbox, les clés de production en mode production. Vérifiez que la devise du panier est acceptée par le Account country (Mexique : MXN, USD ; Colombie : COP, USD ; Pérou : PEN, USD). La page de configuration affiche un avertissement dans chacun de ces cas. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe de clients.
Le paiement a été effectué, mais aucune commande n'a été créée : le client n'est pas revenu de la page 3D Secure et le webhook ne fonctionne pas. Vérifiez que l'URL du webhook est ajoutée dans le tableau de bord OpenPay du mode que vous utilisez, exactement comme l'affichent les réglages, avec les événements listés plus haut. Vérifiez que les clés du mode dans lequel le paiement a été effectué sont renseignées : sans elles, le webhook répond not configured et OpenPay réessaie plus tard. La commande est aussi créée lorsque le client revient dans la boutique ou lorsqu'il essaie de payer à nouveau le même panier.
Le webhook répond ignored (unknown order) : le débit n'a pas été créé par cette boutique, par exemple un débit d'une autre boutique sur le même compte OpenPay. Rien n'est modifié.
Le webhook répond verification failed : l'API OpenPay n'a pas pu être jointe pour lire le débit. OpenPay réessaie le webhook.
Le webhook répond busy : le panier était en cours de mise à jour par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple, le module est désactivé). OpenPay réessaie le webhook. Activez Debug log pour voir la raison.
Le client voit The secure card form could not be loaded : openpay.js ou la bibliothèque antifraude d'OpenPay ne s'est pas chargée dans le navigateur, ou l'identifiant de session d'appareil n'a pas pu être créé. Demandez au client de recharger la page et de réessayer.
Le client voit The payment could not be processed right now : OpenPay a rejeté la requête ou n'a pas répondu. La raison figure dans le journal. Un Merchant ID ou une clé privée incorrects est une cause fréquente. Si OpenPay n'a pas répondu, vérifiez le débit dans le tableau de bord OpenPay avant que le client ne paie à nouveau.
Le client voit This test card cannot be used for real payments : une carte de test sandbox a été utilisée alors que le mode sandbox était désactivé.
La commande est en OpenPay payment on hold après le paiement : lisez les OpenPay notes du bloc (voir Statuts de commande), puis traitez la commande ou remboursez le paiement.
Le remboursement échoue avec un message concernant le mode : la commande a été payée en mode sandbox ou en production, et les clés de ce mode ne sont pas renseignées. Saisissez-les et réessayez.
Le remboursement échoue avec The order is being updated right now : un webhook ou une autre requête mettait à jour la commande au même moment. Réessayez dans un instant.
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox OpenPay 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 de la passerelle, le code de vérification du webhook enregistré et les journaux sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une future réinstallation. Les enregistrements de débits et de remboursements OpenPay ainsi que les statuts de commande Awaiting OpenPay payment et OpenPay payment on hold sont toujours conservés, afin que les commandes payées auparavant puissent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.
OpenPay est une marque commerciale de son propriétaire respectif. Ce module n'est ni affilié à OpenPay ni approuvé par OpenPay.