VibeFox Wompi 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 de PHP plus anciennes.

Devise : peso colombien (COP). Wompi Colombie encaisse en COP, et le moyen de paiement est masqué pour les paniers dans d'autres devises. La page de configuration vous avertit lorsque la devise par défaut de la boutique n'est pas COP.

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 de 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 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 Wompi Payment dans la liste des modules et cliquez sur Configure.

3. Collez 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. Collez les clés sandbox et production du tableau de bord marchand de Wompi et renseignez l'URL d'événements dans Wompi (voir Configuration).

5. Activez Enable/Disable et cliquez sur Save. Testez un paiement en mode sandbox, puis désactivez Sandbox mode pour accepter de vrais paiements.

À l'installation, le module crée deux statuts de commande, Awaiting Wompi payment et Wompi payment on hold. PrestaShop propose un nouveau module de paiement pour les devises, pays et groupes de clients existant à ce moment-là. Vérifiez que COP est autorisé dans Payment > Preferences. Un pays ajouté plus tard doit y être coché avant que ses clients ne voient Wompi.

Configuration

Toute la configuration se trouve sur la page du module : Modules > Module Manager > VibeFox Wompi Payment > Configure. Chaque section comportant des champs a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, un encadré d'état indique le mode actuel, SANDBOX ou PRODUCTION. Lorsqu'une clé de ce mode manque, l'encadré la liste et indique que le moyen de paiement est masqué au moment du 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 seront débités. À l'enregistrement, le module vous avertit si une clé ne commence pas par le préfixe de sa section, et si Wompi est activé mais masqué au moment du paiement parce que des clés manquent.

Wompi

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

Title : le nom du moyen de paiement que voient les clients au moment du paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Wompi. Si vous le laissez vide, le nom du module est utilisé.

Description : le texte affiché sous le moyen de paiement au moment du 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 de 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 : utilise le sandbox Wompi (clés sandbox, sans argent réel). Il change à la fois les clés et l'API Wompi (sandbox.wompi.co ou production.wompi.co). Les tentatives de paiement conservent l'environnement dans lequel elles ont été faites. Par défaut : on. Désactivez-le pour accepter de vrais paiements. Tant qu'il est activé, les clients voient Mode sandbox : aucun paiement réel n'est effectué. sous le moyen de paiement.

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

Les clés publiques s'affichent dans leurs champs. Les clés privées et secrets enregistrés ne sont plus jamais affichés. Le champ reste vide et affiche Enregistré : laissez vide pour le conserver. Saisissez une nouvelle valeur uniquement pour la modifier.

Clear saved secrets : cochez une clé privée ou un secret de l'un des deux environnements et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

URL d'événements (webhook)

Les événements Wompi informent votre boutique qu'une transaction a changé. Dans le tableau de bord marchand de Wompi, section développeurs, renseignez l'URL d'événements affichée dans cette section, pour le sandbox et pour la production. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_wompi_payment/webhook, éventuellement avec un code de langue tel que /es/. Copiez l'URL exactement telle qu'elle est affichée dans la configuration.

Le module 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 webhooks sans signature valide sont rejetés. Après la vérification, la transaction est lue depuis l'API Wompi avec la clé privée de cet environnement, et seules ces données sont utilisées. Sans URL d'événements, la commande n'est créée que lorsque le client revient dans la boutique après avoir payé.

Avancé

Debug log : écrit l'activité des paiements et des webhooks dans logs/wompi_p_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 journalisés, 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 : off.

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

Delete data on uninstall : lorsque l'option est activée, la désinstallation du module supprime sa configuration et le journal. Les tentatives de paiement Wompi et les statuts de commande du module sont toujours conservés, afin que les commandes existantes gardent leurs données Wompi. Par défaut : off.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut Wompi) et confirme. Le module crée une tentative de paiement avec sa propre référence (PS-, le numéro du panier et un horodatage), la signe avec le secret d'intégrité et envoie le client vers Wompi Web Checkout avec le total du panier en COP. L'adresse e-mail du client et le nom de l'adresse de facturation sont transmis à Wompi. Aucune commande n'existe encore à ce stade.

Sur la page de Wompi, le client paie avec n'importe quel moyen de paiement activé dans votre compte Wompi. Wompi renvoie ensuite le client vers 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 revient. Le numéro de transaction présent dans l'adresse de retour n'est pas considéré comme fiable, et seules les transactions créées pour ce panier dans l'environnement de sa tentative sont acceptées. Lors des rechargements de page, la transaction est vérifiée à nouveau au plus une fois toutes les 20 secondes.

Lorsque la transaction est approuvée, la commande est créée et le client voit la page standard de confirmation de commande. Pour un paiement en attente (par exemple PSE, Nequi ou un paiement en espèces), la page affiche Votre paiement Wompi est en attente de confirmation (par exemple PSE, Nequi ou un paiement en espèces). Nous traiterons la commande dès que Wompi confirmera le paiement. Pour une commande en attente, elle affiche Nous avons bien reçu votre paiement Wompi et nous le vérifions. Nous vous contacterons si quelque chose est nécessaire. Si un paiement en attente est refusé par la suite, la page affiche Votre paiement Wompi n'a pas été approuvé. Veuillez nous contacter. S'il est annulé, la page affiche Votre paiement Wompi a été annulé et cette commande a été annulée. Veuillez nous contacter.

Si Wompi n'a pas encore confirmé la transaction lorsque le client revient, une page affiche Nous attendons la confirmation de votre paiement par Wompi. Vous recevrez un e-mail dès qu'il sera confirmé. avec un bouton Check again. L'événement Wompi crée la commande dès son arrivée.

Si le paiement est refusé, aucune commande n'est créée et le panier est conservé. Le client revient au paiement avec Votre paiement Wompi n'a pas été approuvé (...). Vous pouvez réessayer ou choisir un autre moyen de paiement., avec le motif donné par Wompi. Un paiement annulé affiche Votre paiement Wompi a été annulé. Vous pouvez réessayer ou choisir un autre moyen de paiement. Si le client quitte Web Checkout sans payer, le message est Votre paiement Wompi n'a pas été finalisé. Vous pouvez réessayer ou choisir un autre moyen de paiement. Chaque nouvelle tentative reçoit une nouvelle référence. Une fois que le panier a une commande (payée, en attente, Erreur de paiement ou Annulé), il ne peut plus être payé : le client est redirigé vers la page de confirmation de commande.

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 du panier est COP et autorisée pour le module, et que le total est d'au moins COP 1 500. Si le paiement ne peut pas démarrer, le client reste au paiement avec un bref message :

L'URL d'événements fonctionne pendant que la boutique est en mode maintenance et n'est pas bloquée par la restriction de pays de votre boutique.

Le module n'effectue pas de remboursement depuis PrestaShop. Il 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

Pas encore de commande : le client a été envoyé vers Wompi et n'a pas payé, le paiement a été refusé, ou Wompi n'a pas encore confirmé la transaction. Seul le panier existe.

Awaiting Wompi payment : Wompi signale la transaction comme en attente, par exemple des paiements PSE, Nequi ou en espèces qui attendent une confirmation. La commande attend jusqu'à ce que Wompi l'approuve ou la refuse. Une fois approuvée, le paiement est enregistré et la commande passe à Payment accepted.

Payment accepted : la transaction a été approuvée pour le montant du panier en COP. Le paiement est enregistré avec l'identifiant de transaction Wompi, et une note indique la transaction, le type de moyen de paiement (par exemple CARD, PSE ou NEQUI), la référence, le montant et l'environnement.

Wompi payment on hold : Wompi a approuvé un montant ou une devise différents du total de la commande (par exemple, le panier a été modifié 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 l'explique. Vérifiez le paiement dans le tableau de bord Wompi, puis traitez la commande ou remboursez le paiement.

Payment error : une transaction en attente 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.

Canceled : une transaction en attente de la dernière tentative de paiement a été annulée dans Wompi.

Si un second paiement approuvé arrive pour une commande déjà payée, la commande ne change pas. 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 et retours répétés ne dupliquent jamais les notes, e-mails ni paiements.

Bloc de paiement Wompi

La page de commande affiche un bloc Wompi payment avec la référence, l'identifiant de transaction, le statut (avec le statut Wompi), le montant demandé, le montant de la transaction, le moyen de paiement, le message Wompi, un badge SANDBOX pour les paiements sandbox, les Payment attempts du panier lorsqu'il y en a plusieurs, et les Wompi notes de la commande.

Remboursements

Les remboursements ne sont pas envoyés depuis PrestaShop. Remboursez ou annulez le paiement dans le tableau de bord marchand de Wompi, puis enregistrez le remboursement manuellement dans PrestaShop. Une annulation de la transaction de paiement effectuée dans Wompi est ajoutée à la commande sous forme de note.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Wompi Payment est le premier bloc de Modules > Module Manager > VibeFox Wompi Payment > Configure, au-dessus des paramètres. Collez 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) 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-wompi et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de la permission 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-le dans votre compte vibefox.net.

Sans clé active, Wompi n'est pas affiché aux clients au moment du paiement. 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 au moment du paiement. 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 par les événements Wompi et les retours des clients.

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é 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

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 de configuration liste les clés manquantes). Vérifiez aussi que la devise du panier est COP et que le total est d'au moins COP 1 500. Dans Payment > Preferences, vérifiez que le module est autorisé pour COP, le pays du client et le groupe du client.

Le paiement a abouti, mais aucune commande n'a été créée : l'URL d'événements ne fonctionne pas. Dans le tableau de bord Wompi, vérifiez que l'URL d'événements est renseignée pour l'environnement utilisé (sandbox ou production) et qu'elle est exactement celle affichée dans la configuration. Vérifiez que le secret d'événements de cet environnement se trouve dans la section correspondante. La commande est aussi créée lorsque le client revient dans la boutique après avoir payé.

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

L'URL d'événements 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'URL d'événements 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'URL d'événements répond Retry : la commande était en cours de confirmation 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é). Wompi renverra l'événement plus tard. Consultez le champ Log pour connaître la raison.

L'URL d'événements 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 de production.

L'URL d'événements répond Unknown reference : la référence de transaction n'a pas été émise par cette boutique, par exemple parce que le même compte Wompi est utilisé par une autre boutique. Les références d'autres systèmes reçoivent la réponse Ignored.

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

Avertissement à l'enregistrement indiquant que la clé ne commence pas par ... : 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 Wompi payment on hold : lisez les notes du bloc Wompi payment (voir Statuts de commande), puis traitez la commande ou remboursez le paiement dans le tableau de bord Wompi.

Autres erreurs : consultez le champ Log sur la page du module et les Wompi notes de la commande. Les erreurs sont toujours journalisées. Activez Debug log pour plus de détails.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Wompi Payment 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é, la configuration du module et le journal sont supprimés. S'il est désactivé, toute la configuration est conservée pour une réinstallation ultérieure. Les tentatives de paiement Wompi et les statuts de commande Awaiting Wompi payment et Wompi payment on hold sont toujours conservés, de sorte qu'un événement tardif d'un ancien paiement est encore reconnu après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

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