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

Compte Windcave: vous avez besoin d'un compte marchand Windcave avec des identifiants de l'API REST : un nom d'utilisateur API et une clé d'API. Windcave les délivre séparément pour l'environnement de test UAT (uat.windcave.com) et pour la production (sec.windcave.com). Demandez-les au support Windcave ou à votre responsable de compte. Les clés PxPay ne fonctionnent pas avec ce module. Les moyens de paiement que vous souhaitez proposer (cartes, portefeuilles et autres) doivent être activés sur votre compte Windcave.

Notification: votre boutique doit être accessible depuis internet pour que Windcave puisse envoyer sa notification de paiement. Rien ne doit être configuré chez Windcave pour cela.

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 l'envoi terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Windcave Payment Gateway dans la liste des modules et cliquez sur Configure.

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

4. Saisissez votre nom d'utilisateur et votre clé de l'API REST : les identifiants UAT pour le mode test, les identifiants de production pour les paiements réels (voir Configuration).

5. Choisissez le type de transaction et les moyens de paiement, activez Enable/Disable et cliquez sur Save. Effectuez un paiement test avec Test mode activé, puis désactivez Test mode pour encaisser de vrais paiements.

À l'installation, le module crée le statut de commande Windcave payment on hold. PrestaShop propose le nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les limiter dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Windcave Payment Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Tant que le mode test est activé, la page affiche Le mode test est activé : les paiements vont à l'environnement UAT de Windcave et aucun argent réel n'est prélevé. Si le module est activé mais que le mode en cours n'a pas d'identifiant ou de clé API, la page signale que le moyen de paiement est masqué au paiement, par exemple Windcave est activé mais le nom d'utilisateur ou la clé API UAT sont vides : le moyen de paiement est masqué au paiement. Le Title ne peut pas être vide : la page affiche alors Saisissez un titre pour le moyen de paiement. et rien n'est enregistré.

Windcave

Enable/Disable: Enable Windcave 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 au paiement. C'est aussi le nom enregistré dans la commande. Par défaut : Credit/Debit Card (Windcave). Obligatoire.

Description: le texte affiché sous le moyen de paiement au moment de payer. Par défaut : You will be redirected to the secure Windcave payment page to complete your payment.

Windcave REST API

Saisissez les identifiants de l'API REST délivrés par Windcave (nom d'utilisateur et clé d'API, et non les clés PxPay). Les identifiants de production et UAT peuvent être enregistrés côte à côte. Le mode test n'utilise que les identifiants UAT, le mode réel uniquement ceux de production. La section renvoie à la documentation de l'API REST de Windcave.

Test mode: utilise l'environnement de test UAT de Windcave (uat.windcave.com). Aucun argent réel n'est prélevé. Les nouveaux paiements utilisent les identifiants UAT. Les remboursements et les captures sont toujours envoyés dans l'environnement où la commande a été payée. Par défaut : désactivé.

Production API username: le nom d'utilisateur de l'API REST pour sec.windcave.com.

Production API key: la clé de l'API REST pour sec.windcave.com.

UAT API username: le nom d'utilisateur de l'API REST pour uat.windcave.com (mode test).

UAT API key: la clé de l'API REST pour uat.windcave.com (mode test).

Les clés API enregistrées ne sont plus jamais affichées. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.

Clear saved keys: cochez Production API key ou UAT API key et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Notification URL: affiche l'adresse à laquelle Windcave envoie sa notification de paiement (Fail-Proof Result Notification). Avec des URL conviviales, elle ressemble à https://votre-boutique/module/wcp_windcave_payment_gateway/notification. Il n'y a rien à configurer chez Windcave : le module envoie ses adresses de retour et cette adresse de notification avec chaque session de paiement. L'adresse doit être accessible depuis internet, sinon les commandes ne sont confirmées que lorsque le client revient de Windcave. Ni le retour du client ni la notification ne sont signés par Windcave : le module ne leur fait donc jamais confiance seuls. Il lit toujours le résultat de la session via l'API REST de Windcave, avec les identifiants de l'environnement dans lequel la session a été créée.

Payment

Transaction type: la manière dont le paiement est encaissé. Par défaut : Purchase.

Payment methods: les moyens affichés sur la page de paiement Windcave : Cards, Account2Account (virement bancaire néo-zélandais), Apple Pay, Google Pay, PayPal, Alipay, WeChat Pay, UnionPay, Interac, humm. Utilisez Ctrl ou Cmd et cliquez pour en sélectionner plusieurs. Les moyens doivent être activés sur votre compte Windcave. Laissez le champ vide pour afficher tous les moyens activés sur le compte. Par défaut : Cards.

Advanced

Debug log: enregistre les requêtes API et les événements de paiement dans logs/windcave_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Tant que cette option est désactivée, seuls les erreurs et les avertissements sont journalisés. Les clés API, les données de carte et les données personnelles des clients ne sont jamais journalisées. Par défaut : désactivé.

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

Clean uninstall: supprime les réglages et les journaux du module lors de sa désinstallation. Les données de paiement enregistrées avec les commandes (identifiants de transaction Windcave nécessaires aux remboursements) sont toujours conservées. Par défaut : désactivé.

La version du module s'affiche en bas de la page.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut Credit/Debit Card (Windcave)) avec sa description. En mode test, le client voit aussi Test mode : les paiements vont à l'environnement UAT de Windcave, aucun argent réel n'est prélevé. Après confirmation, le module crée une session de paiement Windcave pour le total du panier dans la devise du panier et envoie le client vers la Windcave Hosted Payment Page. Le numéro de panier est transmis comme référence marchande, ainsi que la langue de la boutique et le nom, l'e-mail, le téléphone et l'adresse de facturation du client (et l'adresse de livraison lorsque le panier nécessite une expédition). Aucune commande n'existe encore à ce stade.

Après le paiement, le client revient sur votre boutique. La commande n'est marquée payée qu'après confirmation de Windcave : le module demande à l'API REST de Windcave le résultat de la session, à la fois lorsque le client revient et lorsque la notification de Windcave arrive. Un verrou par panier garantit que le paiement n'est appliqué qu'une fois. La commande est ensuite créée, et le client voit la page standard de confirmation de commande avec Your Windcave payment has been received. Pour une commande en attente (une autorisation ou un paiement ne correspondant pas au panier), la page affiche Your payment was received by Windcave. The shop will check it before processing your order — please do not pay again.

Si le client revient après un paiement approuvé mais que le résultat n'est pas encore connu, une page Payment confirmation affiche We are waiting for Windcave to confirm your payment. You will receive an e-mail as soon as it is confirmed — please do not pay again. et un bouton Check again. La notification crée la commande dès que Windcave confirme le paiement.

Si le client revient sans paiement abouti, la page de paiement affiche l'un de ces messages. Le panier est conservé.

Le client peut réessayer avec le même panier. Une nouvelle tentative vérifie d'abord la session précédente : si elle est déjà payée, la commande est créée et aucun second paiement n'est lancé ; si le client n'a jamais utilisé la page de paiement et que le panier n'a pas changé, il est renvoyé vers la même page. Si le paiement précédent est en cours de confirmation à ce moment-là, le client voit Your previous payment for this order is being confirmed right now. Please wait a minute and check your e-mail before trying again.

Si Windcave ne peut pas démarrer le paiement, le client reste sur la page de paiement avec un bref message : Windcave n'a pas pu démarrer le paiement avec les détails de cette commande, ou le service de paiement est temporairement indisponible. La raison est inscrite dans le journal. Si le mode en cours n'a pas d'identifiants, le client voit This payment method is not available at the moment. Please choose another payment method or contact us.

La notification fonctionne pendant que la boutique est en mode maintenance et n'est pas bloquée par la restriction géographique de votre boutique.

Le module ne propose ni abonnements ni paiements récurrents, ni cartes enregistrées, ni formulaire de carte intégré à votre site (le client paie toujours sur la page Windcave), ni prise en charge de l'API PxPay 2.0, et il n'ajoute aucun surcoût. Si Windcave ajoute un surcoût, la commande est rapprochée de la transaction principale.

Commandes et remboursements

Order statuses

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

Payment accepted: un paiement Purchase a été confirmé et correspond au panier. Le paiement est enregistré avec l'identifiant de transaction Windcave, et une note indique le montant, l'identifiant de transaction, le code d'autorisation, le type de carte avec le numéro masqué et l'environnement (UAT ou production).

Windcave payment on hold (authorised): un paiement Auth a été approuvé mais pas encore capturé. Aucun paiement n'est enregistré sur la commande tant qu'il n'est pas capturé. La note explique comment le capturer ou le libérer.

Windcave payment on hold (does not match): Windcave a signalé un montant, une devise, une référence marchande ou un type de transaction différents de ceux du panier (par exemple, le panier a été modifié dans un autre onglet après le début du paiement). La note liste les écarts. Pour un Purchase dans la devise du panier, le paiement est enregistré avec le montant que Windcave a réellement débité. Vérifiez le paiement dans Windcave Payline avant l'expédition, et remboursez-le si nécessaire.

Refunded: le paiement a été entièrement remboursé ou l'autorisation a été libérée via le module.

Si un paiement approuvé arrive pour une commande annulée, ou un second paiement approuvé pour une commande existante, la commande n'est pas modifiée. Une note avec l'identifiant de transaction vous demande de le rembourser dans Windcave Payline (ou de restaurer manuellement la commande annulée).

Windcave payment block

La page de commande affiche un bloc Windcave payment avec l'identifiant de transaction, l'identifiant de session, le type et le statut de transaction avec l'environnement, le montant payé, le code d'autorisation et la carte, la transaction de capture ou d'annulation, le total payé et le montant remboursé, un badge Test mode (UAT) pour les paiements test, l'historique des remboursements, toutes les sessions Windcave du panier et les Windcave notes de la commande.

Capture (Auth mode)

Pour une commande en Windcave payment on hold avec une autorisation non encore capturée ou libérée, le bloc affiche Capture Windcave payment avec le montant. Cliquez dessus et confirmez Capture the authorised amount through Windcave now? Le montant autorisé est capturé (le total de la commande, sauf si le paiement ne correspond pas à la commande), la commande passe en Payment accepted et le paiement est enregistré avec l'identifiant de la transaction de capture. Si Windcave refuse la capture, le bloc affiche Windcave capture failed: avec la raison, la raison est ajoutée aux notes et la commande reste en attente.

Refunds

Dans le bloc Windcave payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Windcave. Confirmez la question Refund this amount through Windcave? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez avoir le droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. Les remboursements sont décomptés du montant et de la devise approuvés par Windcave : après un écart, vous pouvez donc rembourser jusqu'à ce que le client a réellement payé, et non le total de la commande. Un remboursement après une capture est imputé sur la transaction de capture. Le remboursement est envoyé à l'environnement (UAT ou production) et au compte où le paiement a été effectué ; les identifiants de cet environnement doivent donc être enregistrés. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec l'identifiant de transaction Windcave. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut.

Pour un paiement Auth non capturé, le bouton est Release authorisation (void) et seul le montant total peut être libéré. Un montant partiel génère une erreur vous demandant de rembourser le montant total ou de capturer d'abord le paiement.

Si Windcave refuse le remboursement, le bloc affiche Windcave declined the refund: avec la raison, et aucun remboursement n'est enregistré. Si Windcave traite encore le remboursement, le bloc affiche Windcave has not confirmed the refund yet. See the order notes. et le remboursement n'est pas enregistré. Vérifiez la transaction dans Windcave Payline : si elle a été approuvée, enregistrez le remboursement manuellement ; sinon, réessayez. Une nouvelle tentative du même remboursement n'est pas envoyée deux fois à Windcave.

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 Windcave. Les remboursements effectués dans Windcave Payline ne sont pas signalés à la boutique.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Windcave Payment Gateway est le premier bloc de Modules > Module Manager > VibeFox Windcave Payment 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) 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-windcave et le lien Manage licenses and domains in your account, 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 l'emplacement dans votre compte vibefox.net.

Sans clé active, Windcave n'est pas proposé aux clients au moment de payer. 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 ne pas le tester au moment de payer. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés par la notification ou au retour du client, et les captures et 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 votre travail 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

Windcave n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que le mode en cours dispose des deux identifiants : UAT API username et UAT API key en mode test, Production API username et Production API key en mode réel. La page des réglages affiche un avertissement lorsqu'ils manquent. 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 module n'a pas encore pu obtenir le résultat de Windcave. Consultez le champ Log sur la page du module : les erreurs sont toujours journalisées, par exemple lorsque la session n'a pas pu être vérifiée. Vérifiez que les identifiants de l'environnement du paiement sont enregistrés et corrects. La vérification est répétée lorsque Windcave renvoie la notification (le module répond payment could not be verified yet, retry later avec un code d'erreur, afin que Windcave réessaie), lorsque le client clique sur Check again, et lorsque le client lance un nouveau paiement pour le même panier. Votre serveur doit accepter les requêtes de Windcave vers la Notification URL affichée dans les réglages.

La notification répond order not found : la session n'a pas été créée par cette boutique, par exemple une session d'une autre boutique qui utilise le même compte Windcave. Elle est ignorée.

Authentication failed dans le journal : le nom d'utilisateur ou la clé de l'API REST est incorrect, ou il appartient à l'autre environnement. Les identifiants UAT ne fonctionnent qu'en mode test, ceux de production uniquement en mode réel. Les clés PxPay ne fonctionnent pas.

Le client voit que Windcave n'a pas pu démarrer le paiement avec les détails de cette commande : Windcave a rejeté la demande de session, par exemple à cause de la devise ou d'un moyen de paiement non activé sur votre compte. La raison exacte se trouve dans le journal.

La commande est en Windcave payment on hold après le paiement : lisez les notes du bloc Windcave payment. Soit le paiement est une autorisation Auth qui attend la capture, soit le montant payé, la devise ou la référence marchande diffère du panier. Capturez, expédiez ou remboursez le paiement.

Paiements test et paiements réels : UAT et production sont séparés. Chaque session est vérifiée dans l'environnement où elle a été créée, et les remboursements et captures sont envoyés à l'environnement du paiement, même si vous changez Test mode plus tard.

Un remboursement échoue avec un message concernant l'environnement : le paiement a été effectué en UAT ou en production, et aucun identifiant pour cet environnement n'est enregistré. Saisissez-les et réessayez.

Capture Windcave payment est absent du bloc de la commande : le bouton n'apparaît que pour les commandes en Windcave payment on hold payées avec Auth et non encore capturées ou libérées, et seulement pour les employés autorisés à modifier les commandes.

Où trouver les détails : les erreurs et les avertissements sont toujours écrits dans le journal ; activez Debug log pour journaliser également les requêtes API et les événements de paiement.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Windcave Payment Gateway et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Clean uninstall est activé, les réglages du module 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 sessions, transactions et remboursements Windcave ainsi que le statut de commande Windcave payment on hold sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être remboursées et capturées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Windcave est une marque de son titulaire respectif. Ce module n'est ni affilié à Windcave ni approuvé par Windcave.