VibeFox Conekta 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.

Devise : la devise de la boutique doit être MXN ou USD. Pour les autres devises, le moyen de paiement est masqué.

Compte Conekta : vous avez besoin des clés privées de l'API de votre compte Conekta (test et production) et d'un webhook dans le tableau de bord Conekta (voir Configuration). Seules les clés privées sont utilisées. La clé publique n'est pas nécessaire, car le paiement a lieu sur la page de paiement hébergée par Conekta.

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 envoyer le dossier wcp_conekta_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Conekta > 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 vos clés privées de test et de production, choisissez le mode et ajoutez le webhook dans le tableau de bord Conekta (voir Configuration).

6. Activez Enable / Disable et enregistrez. Testez un paiement en mode test, puis décochez Test mode.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Conekta. Au-dessus des champs, la page vous avertit lorsque Conekta est activé mais que la clé privée du mode actuel est vide (le moyen de paiement est alors masqué au paiement) et lorsque la devise de la boutique n'est ni MXN ni USD. Tant que le mode test est activé, elle affiche Test mode is on: payments are simulated with the test private key. Si vous enregistrez une passerelle activée sans la clé du mode actuel, un message d'erreur vous demande de la saisir.

Général

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

Title: le nom du moyen de paiement que le client voit au paiement. Par défaut : Conekta.

Description: le texte affiché sous le moyen de paiement au paiement. Par défaut : Pay securely with card, OXXO cash or SPEI transfer. You will be redirected to Conekta to complete your payment.

Payment methods: les moyens proposés sur la page de paiement Conekta. Par défaut : carte, espèces et virement bancaire. Les espèces, SPEI et BNPL ne sont disponibles que pour les commandes en MXN (les commandes en USD n'acceptent que les cartes) et doivent être activés dans votre compte Conekta. Si rien n'est sélectionné, la carte est utilisée.

Credit / debit card: paiement par carte.

Cash (OXXO and other stores): le client reçoit une référence et paie en espèces dans un magasin.

Bank transfer (SPEI): le client reçoit une référence et paie par virement bancaire.

Buy now, pay later (BNPL): paiement via une option BNPL, si elle est activée dans votre compte Conekta.

Clés API

Copiez vos clés privées depuis le tableau de bord Conekta, dans Developers > API keys. Les clés de test et de production sont différentes.

Test mode: Enable test mode utilise la clé privée de test. Aucun argent réel n'est débité et un badge TEST MODE s'affiche au paiement. Les remboursements utilisent toujours la clé du mode dans lequel le paiement a été effectué. Par défaut : activé.

Test private key: la clé privée de l'API du mode test de votre compte Conekta.

Live private key: la clé privée de l'API du mode production de votre compte Conekta. Gardez-la secrète.

Chaque commande Conekta mémorise son mode : les notifications et les remboursements utilisent la clé correspondante. Gardez les deux clés renseignées tant que d'anciennes commandes de test restent ouvertes.

Webhook

Le webhook informe votre boutique des paiements effectués après que le client a quitté la page Conekta, par exemple les paiements OXXO ou SPEI. Dans le tableau de bord Conekta, allez dans Developers > Webhooks et ajoutez l'URL indiquée dans cette section, pour le mode test comme pour le mode production. Elle ressemble à https://your-site/wc-api/webhook_wc_conekta/.

Sélectionnez ces événements :

order.paid: la commande a été payée.

order.pending_payment: la commande attend le paiement, par exemple après l'émission d'une référence OXXO ou SPEI.

order.declined: le paiement a été refusé.

order.expired: la page de paiement ou la référence de paiement a expiré.

order.canceled: la commande Conekta a été annulée.

order.refunded: le paiement a été remboursé, par exemple dans le tableau de bord Conekta.

order.charged_back: le client a contesté le paiement (rétrofacturation) ; l'extension ajoute une note à la commande.

Le corps du webhook indique seulement à l'extension quelle commande Conekta a changé. Chaque notification est vérifiée en relisant la commande depuis l'API Conekta avec la clé privée de son mode ; l'en-tête de signature Digest du webhook n'est pas utilisé. Les notifications concernant des commandes Conekta que cette boutique n'a pas créées pour cette commande sont acquittées et ignorées. Sans le webhook, une commande n'est confirmée que lorsque le client revient dans la boutique après avoir payé, ou lors de la tentative de paiement suivante pour la même commande.

Avancé

Debug log: Log API calls and notifications écrit les détails dans WooCommerce > Status > Logs, source wcp_conekta_gateway. Les erreurs sont toujours journalisées. Les journaux ne contiennent jamais de clés API ni de données de contact client. Par défaut : désactivé.

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

Paiement

Le client choisit le moyen de paiement (par défaut Conekta) et passe sa commande. L'extension crée une commande Conekta pour le total de la commande, dans la devise de la commande, avec les articles, la livraison, les taxes et les remises, puis envoie le client sur la page de paiement hébergée par Conekta. Il y paie avec l'un des moyens autorisés.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée payée qu'après confirmation de Conekta : l'extension lit la commande via l'API Conekta à l'arrivée du webhook et au retour du client. Si le paiement ne peut pas encore être confirmé, la page « Commande reçue » affiche We are confirming your payment with Conekta. The order will be updated automatically — please do not pay again. Lorsque le client a choisi OXXO ou SPEI et reçu une référence de paiement, la commande passe en « En attente » et la page affiche Your Conekta payment reference has been issued. The order will be confirmed as soon as the payment is received.

Si le paiement est refusé, la commande passe en « Échouée » et le client revient sur la page Pay for order avec The Conekta payment was not completed. Please try again or choose another payment method. Si la page de paiement a expiré ou a été annulée, le client voit The Conekta payment has expired or was cancelled. Please place the order again. Lorsque le client paie à nouveau une commande, une page de paiement Conekta encore ouverte avec le même montant est réutilisée ; sinon, la précédente est annulée dans Conekta avant la création d'une nouvelle, afin qu'un ancien lien ne puisse pas être payé deux fois. Si la page précédente a déjà été payée, le paiement est enregistré au lieu d'être débité une seconde fois.

Si Conekta ne peut pas démarrer le paiement, le client voit un court message, par exemple The payment could not be started. Please try again in a moment or choose another payment method. La raison technique est écrite 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 WooCommerce High-Performance Order Storage (HPOS). Les textes sont traduits en espagnol (Mexique).

L'extension n'accepte les paiements que sur la page Conekta. Elle n'affiche pas de formulaire de carte sur votre page de paiement et ne gère ni cartes enregistrées, ni abonnements, ni pré-autorisation et capture, ni paiements échelonnés mensuels (MSI).

Commandes et remboursements

Statuts de commande

Pending payment: le client a été redirigé vers Conekta et n'a pas encore payé. La note de commande indique la commande Conekta et le mode.

Processing: Conekta a confirmé le paiement avec le même montant et la même devise (les commandes ne contenant que des produits virtuels téléchargeables passent à « Terminée », la valeur par défaut de WooCommerce). La note de commande indique le moyen de paiement (par exemple la marque de la carte et ses quatre derniers chiffres, OXXO / espèces ou virement SPEI), la commande Conekta et le débit. L'identifiant de transaction de la commande est l'identifiant du débit Conekta (charge ID).

On hold, waiting for OXXO or SPEI: le client a reçu une référence de paiement. La commande passe en « En cours » lorsque Conekta signale le paiement.

On hold after payment: le montant ou la devise reçus de Conekta ne correspondent pas à la commande, un paiement en mode test est arrivé alors que la boutique était en mode production (aucun argent réel n'a été encaissé), ou le paiement est arrivé pour une commande déjà annulée. La note de commande l'explique. Vérifiez le paiement, puis terminez la commande ou remboursez-la. Une commande qui est seulement pré-autorisée chez Conekta passe aussi en « En attente », avec une note invitant à la capturer ou à l'annuler dans le tableau de bord Conekta.

Failed: le paiement a été refusé. La note indique la raison. Le client peut payer à nouveau.

Cancelled: la page de paiement Conekta en cours a expiré ou a été annulée.

Une commande payée ou remboursée n'est jamais rétrogradée ni rouverte. Si un autre paiement Conekta arrive pour une commande déjà payée, une note WARNING vous demande de le rembourser dans le tableau de bord Conekta.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Conekta (le bouton affiche le titre du moyen de paiement). Les remboursements totaux et partiels sont pris en charge. Le remboursement est envoyé à la commande Conekta qui contient le paiement et utilise la clé du mode dans lequel le paiement a été effectué ; cette clé doit donc être renseignée. Si Conekta n'accepte pas le remboursement, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté aux notes de commande avec le montant, le mode, la commande Conekta, l'identifiant du remboursement et le motif.

Les remboursements effectués dans le tableau de bord Conekta arrivent par le webhook et sont ajoutés en note avec le montant remboursé dans Conekta et dans WooCommerce. Ils ne sont pas enregistrés automatiquement comme remboursements WooCommerce. Enregistrez-les manuellement sans utiliser Refund via Conekta. Une rétrofacturation signalée par Conekta est également ajoutée en note.

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 > Conekta. 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, 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 son emplacement de domaine. Libérez l'emplacement dans votre compte vibefox.net.

Sans clé active, Conekta 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é (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 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 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

Conekta n'apparaît pas au paiement : vérifiez que la licence est active, que Enable / Disable est activé, que la clé privée du mode actuel est renseignée (Test private key en mode test, Live private key en mode production) et que la devise de la boutique est MXN ou USD. La page des réglages affiche un avertissement pour chacune de ces conditions.

Le paiement a abouti, mais la commande reste en Pending payment : le webhook ne fonctionne pas. Dans le tableau de bord Conekta, vérifiez que le webhook existe pour le mode utilisé (test ou production), que son URL est exactement celle affichée dans les réglages et que les événements sont sélectionnés. Vérifiez que la clé privée de ce mode est renseignée, car chaque notification est vérifiée avec elle. La commande est aussi confirmée lorsque le client revient dans la boutique ou lorsqu'il tente de payer à nouveau la même commande.

Le webhook répond Temporarily unavailable : l'API Conekta est injoignable, la clé privée du mode de la commande est absente, ou la commande était en cours de traitement par une autre requête. Conekta relance le webhook.

Le webhook répond Verification failed, Invalid payload ou Invalid order id : l'API Conekta n'a pas confirmé la commande, ou la notification n'était pas un événement de commande Conekta valide.

Le webhook répond Ignored : la notification concerne une commande Conekta que cette boutique n'a pas créée pour cette commande (par exemple une autre boutique ou un lien de paiement sur le même compte), ou un objet autre qu'une commande.

Le client voit le message We could not check the status of your previous payment attempt : la page de paiement Conekta précédente de la commande n'a pas pu être lue ; une nouvelle n'est donc pas créée, afin d'éviter un double paiement. Réessayez dans quelques instants.

Le client voit le message Payment gateway is not configured : la clé privée du mode actuel est absente.

La commande est On hold : lisez les notes de la commande. Le client n'a pas encore payé la référence OXXO ou SPEI, le montant ou la devise ne correspondaient pas, ou un paiement en mode test est arrivé alors que la boutique était en mode production.

Le remboursement échoue avec un message concernant le mode test ou production : le paiement a été effectué dans ce mode et sa clé privée n'est pas renseignée. Saisissez-la et réessayez.

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, l'extension continue de fonctionner avec le dernier statut connu.

Pour les développeurs, le readme indique le filtre wc_ckt_supported_currencies pour la liste des devises.

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, les références Conekta enregistrées sur les commandes 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 commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Conekta est une marque de son titulaire respectif. Cette extension n'a aucun lien avec Conekta et n'est pas approuvée par Conekta.