VibeFox Conekta for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les versions antérieures de PHP.

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

Compte Conekta : vous avez besoin des clés API privées 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 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 Conekta Gateway dans la liste des modules et cliquez sur Configure.

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

4. 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).

5. Activez Enable / Disable et cliquez sur Save. Testez un paiement en mode test, puis désactivez Test mode.

À l'installation, le module crée deux statuts de commande, Awaiting Conekta payment et Conekta payment on hold. PrestaShop propose un nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les restreindre dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Conekta Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit lorsque Conekta est activé mais que la clé privée du mode actuel est vide (le mode de paiement est alors masqué au paiement) et lorsque la devise par défaut de la boutique n'est ni MXN ni USD. Tant que le mode test est activé, elle affiche Le mode test est activé : les paiements sont simulés avec la clé privée de test. Si vous enregistrez une passerelle activée sans la clé du mode actuel, un avertissement vous demande de la saisir.

Conekta

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

Title : le nom du mode de paiement que le client voit au paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Conekta. Obligatoire.

Description : le texte affiché sous le mode de paiement au moment du 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 modes proposés sur la page de paiement Conekta. Par défaut : card, cash and bank transfer. 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 et la page vous en avertit lors de l'enregistrement.

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 : utilise la clé privée de test. Aucun argent réel n'est débité, et un badge TEST MODE avec la mention Aucun débit réel ne sera effectué. apparaît sous le mode de paiement au moment du 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 API du mode test de votre compte Conekta.

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

Les clés enregistrées ne sont plus jamais affichées. Le champ reste vide et affiche Enregistrée — laissez vide pour la conserver. Saisissez une nouvelle valeur uniquement pour la modifier.

Clear saved keys : cochez une clé et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

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 sont encore ouvertes.

Webhook

Le webhook informe votre boutique des paiements, par exemple des paiements OXXO ou SPEI effectués après que le client a quitté la page Conekta. Dans le tableau de bord Conekta, allez dans Developers > Webhooks et ajoutez l'URL affichée dans le champ Webhook de la section API keys, pour le mode test et pour le mode production. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_conekta_gateway/webhook, éventuellement avec un code de langue comme /en/. Copiez l'URL exactement telle que les réglages l'affichent.

Sélectionnez ces événements (ils sont aussi listés dans les réglages) :

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

order.pending_payment : la commande attend le paiement, par exemple parce qu'une référence OXXO ou SPEI a été émise.

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

order.expired : le 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) ; le module ajoute une note à la commande.

Le corps du webhook indique seulement au module 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 qui n'ont pas été créées par cette boutique pour ce panier sont acquittées et ignorées. Sans le webhook, une commande n'est créée que lorsque le client revient dans la boutique après avoir payé, ou lors de la prochaine tentative de paiement du même panier.

Avancé

Debug log : consigne les appels API et les notifications dans logs/wc_ckt_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et les avertissements sont toujours consignés, même lorsque ce commutateur est désactivé. Les journaux ne contiennent jamais de clés API ni de données de contact client. Par défaut : désactivé.

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

Delete data on uninstall : lorsqu'il est activé, la désinstallation du module supprime les réglages et le journal. Les transactions et remboursements Conekta, les statuts de commande et les commandes sont toujours conservés, afin que les anciennes commandes puissent encore être confirmées et remboursées après une réinstallation. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le mode de paiement (par défaut Conekta) et confirme. Le module crée une commande Conekta pour le montant total du panier, dans la devise du panier, avec les produits, l'emballage cadeau, les remises, les taxes et la livraison, puis envoie le client sur la page de paiement hébergée par Conekta. Le paiement apparaît sur la page Conekta sous la forme Order # suivi du numéro du panier. Le client y paie avec l'un des modes autorisés. À ce stade, aucune commande n'existe encore.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée comme payée qu'après confirmation de Conekta : le module lit la commande depuis l'API Conekta lorsque le webhook arrive et lorsque le client revient. La commande est alors créée et le client voit la page standard de confirmation de commande avec Votre paiement avec Conekta a bien été reçu. Si le client a choisi OXXO ou SPEI et a reçu une référence de paiement, la commande est créée avec le statut Awaiting Conekta payment et la page affiche Votre référence de paiement Conekta a été émise. La commande sera confirmée dès que le paiement sera reçu. Si la référence expire ensuite, la commande est annulée et sa page de confirmation affiche Votre paiement Conekta n'a pas été finalisé. Veuillez nous contacter au sujet de cette commande.

Si le paiement ne peut pas encore être confirmé lorsque le client revient, une page Confirmation du paiement affiche Nous confirmons votre paiement avec Conekta. La commande sera mise à jour automatiquement — merci de ne pas payer à nouveau. ainsi qu'un bouton Check again. Le webhook crée la commande dès son arrivée.

Si le paiement est refusé, aucune commande n'est créée et le client revient au paiement avec le message Le paiement Conekta n'a pas été finalisé. Veuillez réessayer ou choisir un autre mode de paiement. Si le paiement a expiré ou a été annulé, le message est Le paiement Conekta a expiré ou a été annulé. Veuillez réessayer. Le panier est conservé. Lorsque le client paie à nouveau, une page de paiement Conekta encore ouverte pour 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 avait déjà été payée, la commande est créée au lieu de débiter à nouveau le client.

Si Conekta ne peut pas démarrer le paiement, le client reste sur la page de paiement avec un bref message, par exemple Le paiement n'a pas pu être démarré. Veuillez réessayer dans un instant ou choisir un autre mode de paiement. Les messages de validation envoyés par Conekta, comme un montant minimum, sont affichés tels qu'ils sont envoyés. La raison technique est écrite dans le journal.

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

Le module n'accepte les paiements que sur la page Conekta. Il n'affiche aucun 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

No order yet : le client a été envoyé vers Conekta et n'a pas payé, le paiement a été refusé, ou Conekta n'a pas encore confirmé le paiement. Seul le panier existe.

Payment accepted : Conekta a confirmé le paiement avec le même montant et la même devise. Le paiement est enregistré avec l'identifiant de débit Conekta comme identifiant de transaction, et une note indique le mode de paiement (par exemple la marque de la carte et les quatre derniers chiffres, OXXO / espèces ou virement SPEI), la commande Conekta et le débit.

Awaiting Conekta payment : le client a reçu une référence de paiement OXXO ou SPEI. La commande passe à Payment accepted lorsque Conekta signale le paiement.

Conekta payment on hold : le montant ou la devise reçus de Conekta ne correspondent pas au panier (par exemple, le panier a été modifié après le début du paiement), 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 l'explique, et le paiement est enregistré avec le montant réellement payé. Vérifiez la commande, puis traitez-la ou remboursez le paiement. Une commande qui n'est que pré-autorisée dans Conekta est elle aussi mise en attente, avec une note invitant à la capturer ou à l'annuler dans le tableau de bord Conekta.

Canceled : la référence OXXO ou SPEI d'une commande en attente a expiré, ou sa commande Conekta a été annulée.

Refunded : le paiement a été intégralement remboursé via le module.

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.

Bloc de paiement Conekta

La page de commande affiche un bloc Conekta payment avec la commande Conekta, le débit, le statut du paiement, le montant payé et remboursé, un badge Test mode pour les paiements de test, l'historique des remboursements et les Conekta notes de la commande.

Remboursements

Dans le bloc Conekta payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Conekta. Confirmez la question Rembourser ce montant via Conekta ? Cette action est irréversible. Les remboursements totaux et partiels sont pris en charge. Vous devez disposer du droit de modifier les commandes. Les remboursements sont limités au montant et à la devise que Conekta a réellement débités ; après un écart de montant, vous pouvez donc rembourser jusqu'au montant payé par le client, et non le total de la commande. 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, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec le montant, le mode, la commande Conekta, l'identifiant du remboursement et le motif. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut. Les remboursements sont disponibles une fois que Conekta a signalé le paiement.

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

Les remboursements effectués dans le tableau de bord Conekta arrivent par le webhook et sont ajoutés comme note avec le montant remboursé dans Conekta et dans PrestaShop. Ils ne sont pas enregistrés automatiquement. Mettez la commande à jour manuellement sans utiliser Refund via Conekta. Une rétrofacturation signalée par Conekta est également ajoutée comme note.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Conekta Gateway est le premier bloc de Modules > Module Manager > VibeFox Conekta 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) ainsi que 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-conekta et le lien Gérer les licences et les domaines dans votre compte, 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 : le domaine 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-le dans votre compte vibefox.net.

Sans clé active, Conekta n'est pas proposé aux clients au moment 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. La vitrine de PrestaShop ne sait pas que vous êtes connecté au back office, donc le mode de paiement est aussi masqué pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au paiement. Un rappel apparaît dans Modules > Module Manager, dans l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà commencé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

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 du panier est MXN ou USD. La page des réglages affiche un avertissement lorsque la clé manque ou que la devise de la boutique n'est pas prise en charge. 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. 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 créée lorsque le client revient dans la boutique, ou lorsqu'il essaie de payer à nouveau le même panier.

Le webhook répond Temporarily unavailable : l'API Conekta n'a pas pu être jointe, la clé privée du mode de la commande est absente, le panier était en cours de traitement par une autre requête, ou la commande n'a pas pu être créée (par exemple parce que le module est désactivé). Conekta relance le webhook. Consultez le champ Log pour connaître la raison.

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 qui n'a pas été créée par cette boutique pour ce panier (par exemple une autre boutique ou un lien de paiement sur le même compte), ou un objet autre qu'une commande.

L'URL du webhook affiche Method not allowed dans le navigateur : c'est normal. L'URL n'accepte que les requêtes provenant de Conekta.

Le client voit Nous n'avons pas pu vérifier l'état de votre tentative de paiement précédente : la page de paiement Conekta précédente du panier n'a pas pu être lue, donc une nouvelle n'est pas créée afin d'éviter un double paiement. Réessayez dans un instant.

Le client voit La passerelle de paiement n'est pas configurée : la clé privée du mode actuel est absente.

Le client voit La vérification du paiement a échoué : le lien de retour de Conekta ne correspondait pas au panier. Vérifiez la commande dans le tableau de bord Conekta ; le webhook confirme toujours un paiement réel.

La commande est en Awaiting Conekta payment ou Conekta payment on hold : lisez les Conekta notes dans le bloc de la commande. Le client n'a pas encore payé la référence OXXO ou SPEI, le montant ou la devise ne correspondait pas, un paiement en mode test est arrivé alors que la boutique était en mode production, ou le paiement n'est que pré-autorisé.

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.

Pour les développeurs, le README répertorie les hooks actionWcpConektaSupportedCurrencies, actionWcpConektaOrderRequest, actionWcpConektaAllowedPaymentMethods et actionWcpConektaRefundReason.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Conekta 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 et le journal sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une réinstallation ultérieure. Les transactions et remboursements Conekta ainsi que les statuts de commande Awaiting Conekta payment et Conekta payment on hold sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Conekta est une marque de commerce de son propriétaire respectif. Ce module n'est ni affilié à Conekta ni approuvé par Conekta.