VibeFox OpenPay for WooCommerce — Aide

Prérequis

WordPress : 6.0 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.

HTTPS : votre site 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 l'extension les maintient 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 tokénisée dans le navigateur par openpay.js. Les champs de carte n'ont pas de nom et ne sont jamais envoyés à votre serveur. Comme le formulaire de carte se trouve sur votre page, votre périmètre PCI DSS est SAQ A-EP ; renseignez-vous auprès de votre acquéreur.

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 transférer le dossier wcp_openpay_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > OpenPay > Manage, ou cliquez sur Settings sous le nom de l'extension dans 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. Choisissez le Account country et saisissez les clés sandbox et production (voir Configuration).

6. Recommandé : ajoutez l'URL du webhook dans le tableau de bord OpenPay (voir Configuration).

7. Activez Enable / Disable et enregistrez. Testez un paiement avec les cartes de test du sandbox OpenPay, puis décochez Sandbox mode pour encaisser de vrais paiements.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > OpenPay. 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é sur la page de paiement), lorsque la devise de la boutique n'est pas acceptée par le pays de compte choisi, et affiche Sandbox mode is enabled — no real charges are made. tant que le mode sandbox est activé. Dans la liste des moyens de paiement, OpenPay est signalé comme nécessitant une configuration tant que le mode actuel ne dispose pas des trois clés, et un badge de mode test s'affiche 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, vous voyez aussi un message indiquant que la passerelle reste masquée sur la page de paiement.

Général

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 sur la page de paiement. Par défaut : Credit or debit card (OpenPay).

Description: le texte affiché au-dessus du formulaire de carte sur la page de paiement. 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 : Use the OpenPay sandbox (test keys, no real charges) bascule à la fois les clés et l'API vers le sandbox. Un badge SANDBOX MODE s'affiche au paiement tant qu'il est activé. Par défaut : activé. Décochez-le pour encaisser 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 tokéniser 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 de la version 1.0 de l'extension (un seul jeu de clés et un indicateur sandbox) sont automatiquement transférées vers les champs sandbox ou production.

Webhook

Le webhook n'est pas obligatoire, mais il est recommandé. Il confirme les paiements lorsque le client ne revient pas de la page 3D Secure, par exemple après avoir fermé le navigateur. Dans le tableau de bord OpenPay, allez dans Settings > Webhooks et ajoutez l'URL affichée dans cette section des réglages. Elle ressemble à https://your-site/wc-api/webhook_wc_openpay/. Copiez-la exactement comme les réglages l'affichent. 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 :

OpenPay ne signe pas les webhooks ; l'extension ne fait donc jamais confiance à la notification elle-même. Elle s'en sert uniquement pour trouver le débit, puis relit le débit depuis l'API OpenPay avec la clé privée du mode dans lequel la commande a été payée. Une notification concernant un débit que cette boutique n'a pas créé est ignorée.

Avancé

Debug log : Log payment steps (errors are always logged) écrit les étapes de paiement dans WooCommerce > Status > Logs, source wcp_openpay_gateway. Les erreurs et avertissements sont journalisés même lorsque l'option est désactivée. Les clés, données de carte et données client ne sont jamais journalisées. Par défaut : désactivé.

Delete data on uninstall : Remove the gateway settings and logs when the plugin is deleted. Par défaut : désactivé.

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). Lorsque la commande est passée, openpay.js transforme la carte en jeton à usage unique dans le navigateur, et la bibliothèque antifraude d'OpenPay ajoute un identifiant de session d'appareil. Seules ces deux valeurs sont envoyées à votre boutique.

L'extension crée ensuite le débit avec 3D Secure pour le total de la commande, dans la devise de la commande, 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 (le numéro de commande et un suffixe court). La description du débit est Order #, le numéro de commande et le nom de votre site. Le nom, l'e-mail et le téléphone du client sont transmis à OpenPay ; aucun compte client OpenPay n'est créé. La commande reste En attente de paiement tant que le client est sur la page 3D Secure.

Lorsque le client revient, l'extension lit le débit depuis l'API OpenPay. La commande n'est marquée payée qu'après confirmation d'OpenPay : le débit doit appartenir à cette commande, être finalisé et correspondre exactement au total et à la devise de la commande. Si le résultat n'est pas encore connu, la page de confirmation de commande affiche We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. Le webhook met ensuite la commande à jour.

Si la carte est refusée ou si le 3D Secure échoue, le client revient sur la page Pay for order 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. Avant une nouvelle tentative, l'extension vérifie le débit précédent de la commande : s'il était bien payé, la commande est marquée payée sans second débit ; s'il est toujours en cours de traitement, le client voit qu'un paiement précédent est encore en traitement et ne doit pas payer à nouveau ; si son état ne peut pas être vérifié, aucune nouvelle tentative n'est faite et le client est invité à réessayer dans quelques minutes.

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 vont dans les notes de commande et 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 WooCommerce High-Performance Order Storage (HPOS). Il est masqué au paiement lorsqu'il est désactivé, lorsque les clés du mode actuel sont incomplètes ou lorsque la devise de la commande n'est pas acceptée par le pays de compte.

L'extension n'accepte que les paiements par carte, avec capture immédiate. Elle 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

En attente de paiement : le client est sur la page 3D Secure ou n'a pas fini de payer. Une note indique l'identifiant du débit.

En cours : le paiement a été confirmé. C'est le statut WooCommerce habituel après paiement ; les commandes ne contenant que des produits virtuels téléchargeables passent à Terminée. La note de commande indique l'identifiant du débit et le mode (production ou sandbox). L'identifiant de transaction est l'identifiant de débit OpenPay.

En attente : le débit est en cours et pas encore capturé ; ou OpenPay signale un débit finalisé avec un montant ou une devise différent de la commande (la commande n'est pas marquée payée et la note indique l'écart) ; ou un paiement est arrivé pour une commande déjà annulée. Vérifiez la commande dans le tableau de bord OpenPay, puis exécutez-la ou remboursez le paiement là-bas.

Échouée : la carte a été refusée à la création du débit, ou la dernière tentative a échoué, a été annulée ou a expiré. Le client peut payer à nouveau.

Si un second débit finalisé 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.

Remboursements

Pour les comptes du Mexique et du Pérou : ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Credit or debit card (OpenPay) (le bouton affiche le titre de votre moyen de paiement). Les remboursements totaux et partiels sont pris en charge. Le remboursement est envoyé dans le mode et le pays de compte dans lesquels la commande a été payée ; gardez donc les clés sandbox renseignées tant que des commandes sandbox doivent encore être remboursées. Si OpenPay refuse le remboursement, WooCommerce affiche l'erreur, par exemple OpenPay refund failed: ..., et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté aux notes de commande avec l'identifiant de remboursement OpenPay.

OpenPay Colombie ne prend pas en charge les remboursements de carte via l'API, comme dans les extensions officielles d'OpenPay. Pour la Colombie, le bouton de remboursement n'est pas proposé ; remboursez le débit dans le tableau de bord OpenPay.

Les remboursements et contestations effectués dans le tableau de bord OpenPay arrivent par webhook et sont ajoutés une seule fois aux notes de commande. Ils ne sont pas enregistrés automatiquement comme remboursements WooCommerce. Si nécessaire, créez un remboursement manuel dans WooCommerce, sans passer par le bouton OpenPay.

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 > OpenPay. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, et votre domaine. Utilisez Check now pour revérifier 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 son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, OpenPay n'est pas proposé aux clients sur la page de 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 connectés voient toujours le moyen de paiement, marqué (unlicensed — visible to admins only), afin de pouvoir configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. Les commandes existantes ne sont pas touchées : les paiements déjà lancés sont toujours confirmés, et les remboursements fonctionnent.

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

Dépannage

OpenPay n'apparaît pas sur la page de paiement : 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 de la boutique est acceptée par le Account country (Mexique : MXN, USD ; Colombie : COP, USD ; Pérou : PEN, USD). La page de réglages affiche un avertissement dans chacun de ces cas.

Le paiement a abouti, mais la commande reste En attente de paiement : 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 utilisé, exactement comme les réglages l'affichent, avec les événements indiqués plus haut. Vérifiez que les clés du mode dans lequel la commande a été payée sont renseignées : sans elles, le webhook répond not configured et OpenPay réessaie plus tard.

Le webhook répond ignored (unknown order) : le débit n'a pas été créé par cette boutique pour cette commande, 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 était injoignable pour lire le débit. OpenPay réessaie le webhook.

Le webhook répond busy : la commande était en cours de mise à jour par une autre requête au même moment. OpenPay réessaie le webhook.

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é dans le navigateur, ou l'identifiant de session de l'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 les notes de commande et dans le journal, source wcp_openpay_gateway. Un Merchant ID ou une clé privée erronés sont une cause typique. 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.

« This test card cannot be used for real payments » : une carte de test sandbox a été utilisée alors que le mode sandbox est désactivé.

La commande est En attente après le paiement : lisez la note de commande. Le débit est toujours en cours, le montant ou la devise payés diffère de la commande, ou le paiement est arrivé après l'annulation de la commande.

Le remboursement échoue avec un message sur le mode : la commande a été payée en mode sandbox ou production, et les clés de ce mode ne sont pas renseignées. Saisissez-les et réessayez.

Le bloc de licence affiche une erreur : suivez le message affiché. 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, l'extension continue de fonctionner avec le dernier statut connu.

Désinstallation

Désactiver l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis 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, le code de vérification du webhook enregistré et les journaux de l'extension 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 de commande sont toujours conservées : les commandes existantes gardent leurs notes de paiement, leurs identifiants de transaction et les données de débit nécessaires aux remboursements après une réinstallation.

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