VibeFox Wompi for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

WooCommerce : 7.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Devise de la boutique : peso colombien (COP). Wompi Colombie encaisse en COP, et le moyen de paiement est masqué pour les commandes dans d'autres devises.

Compte Wompi : un compte marchand Wompi Colombie. Chaque environnement (sandbox et production) comporte quatre clés : clé publique, clé privée, secret d'événements et secret d'intégrité. Vous les trouvez dans le tableau de bord marchand Wompi (comercios.wompi.co), dans la section développeurs. Wompi El Salvador et Panama utilisent d'autres API et ne sont pas pris en charge.

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_wompi_payment dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Réglez la devise de la boutique sur peso colombien (COP) dans WooCommerce > Settings > General.

4. Ouvrez les réglages : WooCommerce > Settings > Payments > Wompi, ou cliquez sur Settings sous le nom de l'extension sur la page Plugins.

5. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

6. Collez les clés sandbox et production depuis le tableau de bord marchand Wompi et définissez l'Events URL dans Wompi (voir Configuration).

7. Activez Enable/Disable. Testez un paiement en mode sandbox, puis décochez Sandbox mode pour accepter de vrais paiements.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Wompi. Au-dessus des champs, un encadré d'état affiche le mode actuel, SANDBOX ou PRODUCTION. Lorsqu'une clé de ce mode manque, l'encadré la signale et indique que le moyen de paiement est masqué au paiement tant que toutes les clés de cet environnement ne sont pas renseignées. Lorsque toutes les clés sont renseignées, il indique si de vrais paiements sont débités. À l'enregistrement, l'extension vous avertit si une clé ne commence pas par le préfixe de sa section, et si Wompi est activé mais masqué au paiement faute de clés. Dans la liste des moyens de paiement, Wompi est marqué comme nécessitant une configuration tant que le mode actuel n'a pas ses quatre clés. Les clés de la version 1.0 sont automatiquement déplacées vers la section Sandbox ou Production correspondante lors de la mise à jour.

Général

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

Title : le nom du moyen de paiement que voient les clients au paiement. Par défaut : Wompi.

Description : le texte affiché sous le moyen de paiement au paiement. Par défaut : Pay securely with Wompi: cards, PSE, Nequi, Bancolombia and more.

Compte Wompi

Copiez les clés depuis le tableau de bord marchand Wompi (comercios.wompi.co), section développeurs. Chaque environnement a sa propre clé publique, clé privée, secret d'événements et secret d'intégrité.

Sandbox mode : Use the Wompi sandbox (sandbox keys, no real money). Cela change à la fois les clés et l'API Wompi (sandbox.wompi.co ou production.wompi.co). Les commandes conservent l'environnement dans lequel elles ont été payées. Par défaut : activé. Décochez pour accepter de vrais paiements.

Clés sandbox

Les quatre clés du sandbox Wompi. Elles commencent par pub_test_, prv_test_, test_events_ et test_integrity_.

Public key : la clé publique sandbox (pub_test_...). Elle identifie votre compte sur Wompi Web Checkout.

Private key : la clé privée sandbox (prv_test_...). Elle sert à lire les transactions depuis l'API Wompi.

Events secret : le secret d'événements sandbox (test_events_...). Il vérifie la signature des événements Wompi.

Integrity secret : le secret d'intégrité sandbox (test_integrity_...). Il signe la demande de paiement envoyée au Web Checkout.

Clés production

Les quatre clés de l'environnement de production Wompi. Elles commencent par pub_prod_, prv_prod_, prod_events_ et prod_integrity_.

Public key : la clé publique de production (pub_prod_...).

Private key : la clé privée de production (prv_prod_...).

Events secret : le secret d'événements de production (prod_events_...).

Integrity secret : le secret d'intégrité de production (prod_integrity_...).

URL d'événements (webhook)

Les événements Wompi informent votre boutique qu'une transaction a changé. Dans le tableau de bord marchand Wompi, section développeurs, définissez l'Events URL affichée dans cette section des réglages, pour le sandbox et pour la production. Elle ressemble à https://your-site/wc-api/wompi_p/. Copiez l'URL exactement telle qu'elle est affichée dans les réglages.

L'extension utilise cet événement :

Les autres événements reçoivent la réponse Ignored. Chaque événement est vérifié avec le secret d'événements de son environnement (sandbox ou production). Les événements sans signature valide sont rejetés. Après la vérification, la transaction est lue depuis l'API Wompi, et seules ces données sont utilisées. Sans l'Events URL, une commande n'est confirmée que lorsque le client revient dans la boutique après avoir payé.

Avancé

Debug log : Log payment and webhook activity enregistre l'activité des paiements et des événements dans WooCommerce > Status > Logs, source wcp_wompi_payment. Les erreurs sont toujours journalisées, même lorsque cette option est désactivée. Les clés, les secrets et les données clients ne sont jamais journalisés. Par défaut : désactivé.

Delete data on uninstall : Remove the plugin settings and logs when the plugin is deleted. La désactivation ne supprime jamais rien. Les données de commande sont toujours conservées. Par défaut : désactivé.

Paiement

Le client choisit le moyen de paiement (par défaut Wompi) et passe la commande. En mode sandbox, le paiement affiche Sandbox mode: no real payment is made. sous la description. L'extension crée une tentative de paiement avec sa propre référence (WC-, le numéro de commande et un horodatage), la signe avec le secret d'intégrité et envoie le client vers Wompi Web Checkout avec le total de la commande en COP. L'e-mail de facturation et le nom du client sont transmis à Wompi. Une note sur la commande enregistre l'environnement, la référence et le montant.

Sur la page Wompi, le client paie avec n'importe quel moyen de paiement activé dans votre compte Wompi. Wompi renvoie ensuite le client sur la page de commande reçue de votre boutique. La commande n'est marquée payée qu'après confirmation de Wompi : par un événement signé ou par une requête côté serveur vers l'API Wompi lorsque le client arrive sur cette page. Le numéro de transaction présent dans l'adresse de retour elle-même n'est pas considéré comme fiable. En cas de rechargement de la page, la transaction est revérifiée au plus une fois toutes les 20 secondes.

Seules les transactions créées pour cette commande peuvent la payer, et uniquement dans l'environnement de la tentative. Un client peut payer à nouveau une commande non payée, par exemple depuis la page Pay for order. Chaque tentative reçoit une nouvelle référence.

Le moyen de paiement n'est affiché que lorsque la licence est active, que les quatre clés du mode actuel sont renseignées, que la devise de la commande est le COP et que le total est d'au moins COP 1 500. Si le paiement ne peut pas démarrer, le client voit un bref message et peut choisir un autre moyen de paiement :

Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est compatible avec le stockage haute performance des commandes de WooCommerce (HPOS). Les traductions espagnoles pour la Colombie et l'Espagne sont incluses.

L'extension n'effectue pas de remboursement depuis WooCommerce. Elle ne gère ni cartes enregistrées, ni abonnements, ni champs de carte sur votre site : toutes les données de paiement sont saisies chez Wompi.

Commandes

Statuts de commande

Pending payment: le client a été envoyé vers Wompi et n'a pas encore payé, ou Wompi n'a pas encore confirmé la transaction.

On hold (pending payment): Wompi signale la transaction comme en attente, par exemple des paiements PSE, Nequi ou en espèces qui attendent une confirmation. La commande reste en attente jusqu'à ce que Wompi l'approuve ou la refuse.

Processing or Completed: la transaction a été approuvée. Le standard WooCommerce s'applique : En cours, ou Terminée pour les commandes ne contenant que des produits virtuels téléchargeables. La note de commande affiche la transaction Wompi, le type de moyen de paiement (par exemple carte, PSE ou Nequi) et la référence. L'ID de transaction de la commande est l'ID de transaction Wompi.

On hold after payment: Wompi a approuvé un montant ou une devise différent du total de la commande (par exemple, la commande a été modifiée après le début du paiement), ou le paiement a été approuvé après l'annulation de la commande. La commande n'est pas marquée payée. La note de commande l'explique. Vérifiez le paiement dans le tableau de bord Wompi, puis traitez la commande ou remboursez le paiement.

Failed: la transaction de la dernière tentative de paiement a été refusée ou s'est terminée par une erreur. Le message de Wompi est ajouté à la note. Les résultats des tentatives plus anciennes ne modifient pas la commande.

Cancelled: la transaction de la dernière tentative de paiement a été annulée dans Wompi avant que la commande ne soit payée.

Si un second paiement approuvé 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 Wompi. Si la transaction de paiement est annulée dans Wompi, une note vous demande de vérifier la commande. Un paiement tardif pour une commande remboursée ajoute seulement une note. Les événements répétés et les retours ne créent jamais de notes, d'e-mails ou de mouvements de stock en double.

Remboursements

Les remboursements ne sont pas envoyés depuis WooCommerce. Remboursez ou annulez le paiement dans le tableau de bord marchand Wompi, puis enregistrez un remboursement manuel dans WooCommerce. Une annulation effectuée dans Wompi est ajoutée à la commande sous forme de 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 > Wompi. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche l'état, par exemple la date jusqu'à laquelle la licence est active et votre domaine. Utilisez Check now pour revérifier l'état, 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, Wompi n'est pas affiché 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 que vous puissiez 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 affectées : les paiements déjà lancés sont toujours confirmés par les événements Wompi et les retours des clients.

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

Dépannage

Wompi n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que les quatre clés du mode actuel sont renseignées (l'encadré d'état de la page des réglages liste les clés manquantes). Vérifiez aussi que la devise de la commande est le COP et que le total est d'au moins COP 1 500.

Le paiement a abouti, mais la commande reste en Pending payment : l'Events URL ne fonctionne pas. Dans le tableau de bord Wompi, vérifiez que l'Events URL est définie pour l'environnement utilisé (sandbox ou production) et qu'elle correspond exactement à celle affichée dans les réglages. Vérifiez que le secret d'événements de cet environnement se trouve dans la section correspondante. La commande est aussi confirmée lorsque le client revient dans la boutique après avoir payé.

L'Events URL répond Not configured : le secret d'événements de l'environnement de l'événement est vide. Collez-le dans les réglages.

L'Events URL répond Invalid signature : le secret d'événements appartient à un autre environnement ou à un autre compte. Recopiez-le depuis le tableau de bord Wompi.

L'Events URL répond Transaction lookup failed : l'API Wompi n'a pas renvoyé la transaction, par exemple à cause d'une mauvaise clé privée ou d'un problème réseau. Wompi renverra l'événement plus tard.

L'Events URL répond Busy, retry : la commande était en cours de mise à jour par une autre requête au même moment. Wompi renverra l'événement plus tard.

L'Events URL répond Environment mismatch : une transaction sandbox est arrivée pour une tentative de paiement en production, ou l'inverse. Les paiements sandbox ne confirment jamais les commandes en production.

Avertissement à l'enregistrement « The key does not start with ... » : une clé a été collée dans la mauvaise section. Les clés sandbox commencent par pub_test_, prv_test_, test_events_ et test_integrity_, les clés de production par pub_prod_, prv_prod_, prod_events_ et prod_integrity_.

La commande est On hold avec une note sur le montant : le montant ou la devise approuvés diffèrent du total de la commande. Vérifiez le paiement dans le tableau de bord Wompi, puis terminez ou remboursez la commande manuellement.

Autres erreurs : ouvrez les notes de commande ou WooCommerce > Status > Logs, source wcp_wompi_payment. Les erreurs sont toujours journalisées. Activez Debug log pour plus de détails. Les développeurs peuvent autoriser une autre devise avec le filtre wompi_p_supported_currencies si leur compte Wompi l'accepte.

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 état connu.

Désinstallation

La désactivation de 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 l'état de licence de cette extension sont toujours supprimés. Les réglages de la passerelle et les journaux de l'extension ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils restent disponibles pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement, leurs données Wompi et leurs ID de transaction.

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