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

Compte Worldline : un compte marchand Worldline Direct (anciennement Ingenico Direct). Les comptes de test et de production sont distincts et ont des identifiants différents. Pour chaque compte, vous avez besoin du Merchant ID (votre PSPID), d'un API Key ID avec sa Secret API Key, ainsi que d'une clé de webhook avec son secret. Tous sont créés dans le Merchant Portal de Worldline (voir Configuration).

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 Worldline Gateway 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. Saisissez les identifiants de test, cliquez sur Save, puis sur Test credentials.

5. Ajoutez l'URL du webhook dans le Merchant Portal du compte de test, puis saisissez la clé et le secret du webhook (voir Configuration).

6. Activez Enable/Disable et effectuez un paiement de test. Saisissez ensuite les identifiants de production, répétez la configuration du webhook sur votre compte de production, cliquez sur Live credentials et désactivez Test Mode.

À l'installation, le module crée deux statuts de commande : Awaiting Worldline capture et Worldline payment on hold. PrestaShop active un nouveau module de paiement pour les pays actifs à ce moment-là. Vérifiez les devises, les pays et les groupes de clients dans Payment > Preferences, et cochez-y les pays que vous ajouterez plus tard.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Worldline Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit si les identifiants du mode actuel (Merchant ID, API Key ID, Secret API Key) sont incomplets, car le moyen de paiement est alors masqué au moment de la finalisation de la commande. Tant que le mode test est activé, la page affiche Test mode is on (pre-production environment): no real money is charged.

Worldline (Ingenico)

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

Title : le nom du moyen de paiement que voit le client à la finalisation de la commande. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Worldline. Obligatoire.

Description : le texte affiché sous le moyen de paiement à la finalisation de la commande. Par défaut : Pay securely via Worldline.

Worldline Direct API

Obtenez les identifiants dans le Merchant Portal de Worldline du compte de test et du compte de production. Votre PSPID correspond au Merchant ID. Developer > Payment API crée l'API Key ID et la Secret API Key, Developer > Webhooks crée la clé et le secret du webhook. La section contient des liens vers les deux portails et vers la documentation de Worldline.

Test Mode : bascule à la fois le point d'accès de l'API et les identifiants. Le mode test utilise l'environnement de préproduction et les identifiants de test, le mode production utilise l'environnement de production et les identifiants réels. Par défaut : activé. Désactivez-le pour encaisser de vrais paiements. Tant que le mode test est activé, les clients voient Test mode — no real money is charged. sous le moyen de paiement.

Compte de test (préproduction)

Test Merchant ID (PSPID) : le PSPID de votre compte de test.

Test API Key ID : l'API Key ID créé dans Developer > Payment API du compte de test.

Test Secret API Key : la Secret API Key qui correspond à cet API Key ID.

Test Webhook Key ID : facultatif. Lorsqu'il est renseigné, seuls les webhooks envoyés avec cette clé sont acceptés.

Test Webhook Secret : le secret du webhook du compte de test. Il sert à vérifier la signature de chaque webhook.

Compte de production (live)

Live Merchant ID (PSPID) : le PSPID de votre compte de production.

Live API Key ID : l'API Key ID créé dans Developer > Payment API du compte de production.

Live Secret API Key : la Secret API Key qui correspond à cet API Key ID.

Live Webhook Key ID : facultatif. Lorsqu'il est renseigné, seuls les webhooks envoyés avec cette clé sont acceptés.

Live Webhook Secret : le secret du webhook du compte de production.

Les clés secrètes et les secrets de webhook enregistrés ne sont plus jamais affichés. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que si vous voulez la modifier.

Clear saved secrets : cochez un secret et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

Check credentials : les boutons Test credentials et Live credentials vérifient les identifiants enregistrés de chaque compte par un appel de test vers Worldline. Enregistrez d'abord vos modifications. La réponse apparaît en haut de la page, par exemple Test credentials: connection successful., API credentials are not configured. ou l'erreur renvoyée par Worldline.

Webhooks

Le webhook informe votre boutique des paiements même lorsque le client ne revient pas sur la boutique, par exemple après avoir fermé le navigateur ou lorsqu'un paiement est confirmé plus tard. Dans le Merchant Portal, ouvrez Developer > Webhooks du compte de test et ajoutez l'URL affichée dans Endpoint URL de cette section. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_worldline_gateway/webhook, avec éventuellement un code de langue comme /en/. Copiez l'URL exactement telle qu'elle est affichée dans les réglages : elle doit répondre sans redirection. Saisissez ensuite l'identifiant et le secret de la clé du webhook dans Test Webhook Key ID et Test Webhook Secret. Faites de même dans le compte de production avec les champs de production.

Le module répond automatiquement à la requête de vérification de l'endpoint envoyée par Worldline. Il traite les événements de paiement (changements de statut des paiements) et les événements de remboursement (changements de statut des remboursements). Les autres événements sont acceptés et ignorés. Les webhooks sans signature valide sont rejetés. Un événement doit être signé avec le secret du compte dans lequel le paiement a été effectué : un webhook de test ne confirme donc jamais un paiement réel. Un webhook est aussi ignoré s'il provient d'un Merchant ID différent de celui du compte dont le secret l'a signé. Sans webhook, une commande n'est créée que lorsque le client revient sur la boutique après avoir payé.

Page de paiement et commandes

Payment page template : nom facultatif d'un modèle (variante) de page de paiement hébergée, importé dans le Merchant Portal, par exemple SimplifiedCustomPaymentPage. Laissez ce champ vide pour utiliser la page par défaut de Worldline.

Order Status After Payment : le statut de la commande une fois que Worldline confirme le paiement capturé. Les paiements sont toujours demandés en vente directe (autorisation et capture).

Les paiements autorisés attendent dans Awaiting Worldline capture. Les écarts de montant ou de devise passent toujours en Worldline payment on hold.

Avancé

Logging : enregistre toutes les requêtes API et tous les webhooks dans logs/wlg_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 données de carte et les données personnelles sont masqué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.

Delete Data : lorsque cette option est activée, la désinstallation du module supprime les réglages du module et le journal. Les transactions et remboursements Worldline ainsi que les statuts de commande du module sont toujours conservés, car les commandes existantes en ont besoin pour les remboursements. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut Worldline) et confirme. Le module crée une page de paiement hébergée Worldline pour le total du panier dans la devise du panier, et envoie le client vers la page de paiement de Worldline. Il y paie par carte, par portefeuille électronique ou par un autre moyen de paiement activé dans votre compte Worldline. Le nom de facturation, l'adresse, l'e-mail et le téléphone sont transmis à Worldline, et la page de paiement s'ouvre dans la langue du client lorsque Worldline la prend en charge. Chaque tentative de paiement reçoit sa propre référence, composée de l'identifiant du panier et d'une partie aléatoire. Aucune commande n'existe encore à ce stade.

Après le paiement, le client revient sur votre boutique. Le module vérifie ce retour par rapport à la tentative enregistrée et lit le statut du paiement auprès de Worldline, côté serveur. La commande n'est marquée comme payée qu'après confirmation de Worldline : soit par cette vérification de statut, soit par un webhook signé. La commande est alors créée, et le client voit la page standard de confirmation de commande avec le message Your payment with Worldline has been received. Si le paiement est autorisé mais pas encore capturé, la page affiche Your payment is authorized. The order is confirmed as soon as Worldline confirms the capture. Si le paiement d'une telle commande échoue plus tard, la page affiche Your Worldline payment was not completed. Please contact us about this order.

Si le paiement n'a pas été effectué, aucune commande n'est créée, le panier est conservé et le client revient à l'étape de paiement avec un message :

Si le statut n'a pas encore pu être vérifié, une page Payment confirmation affiche We could not confirm your payment yet. If you completed the payment, please do not pay again — you will receive a confirmation as soon as Worldline confirms it. avec les boutons Check again et Back to checkout. Le webhook crée la commande dès son arrivée.

Lorsque le client paie à nouveau le même panier, le module vérifie d'abord la tentative précédente. Si elle a été payée entre-temps, le client accède directement à la confirmation de commande et n'est pas débité deux fois. Si la page de paiement précédente est encore ouverte pour le même montant et le même mode, et qu'elle a été créée il y a moins de 30 minutes, le client y est renvoyé.

Si Worldline ne peut pas démarrer le paiement, le client reste à l'étape de paiement avec Payment error: Could not create checkout session. Please try again. La raison est écrite dans le journal. Si les identifiants du mode actuel sont manquants, le client voit This payment method is not available at the moment. Please choose another payment method.

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

Le module accepte les paiements uniques en vente directe sur la page de Worldline. Il ne gère ni cartes enregistrées ni tokenisation, ni abonnements, ni formulaire de carte intégré, ni mode autorisation seule avec capture ou annulation depuis PrestaShop, ni surcharge, ni enregistrement automatique des webhooks.

Commandes et remboursements

Statuts de commande

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

Payment accepted or Delivered : le paiement a été capturé. Le statut suit Order Status After Payment. Le paiement est enregistré avec l'identifiant de paiement Worldline comme identifiant de transaction, et une note indique le montant, l'identifiant du paiement et le mode de confirmation (webhook signé ou vérification du statut).

Awaiting Worldline capture : Worldline signale le paiement comme autorisé ou la capture comme demandée, mais pas encore capturée. Aucun paiement n'est encore enregistré. La commande passe au statut payé lorsque le webhook confirme la capture. Si la note indique que le paiement n'est pas capturé, capturez-le dans le Merchant Portal de Worldline.

Worldline payment on hold : le paiement ne correspond pas au panier, par exemple si le montant ou la devise diffèrent (le panier a été modifié après le début du paiement) ou si le paiement appartient à une autre tentative. La note indique le montant payé, le total de la commande et la référence. Vérifiez la commande et traitez-la, ou remboursez le paiement.

Payment error : Worldline a refusé ou annulé le paiement d'une commande qui attendait la capture.

Refunded : le paiement a été entièrement remboursé via le module.

Si un paiement arrive pour une commande annulée ou remboursée, la commande n'est pas rouverte. Une note vous invite à rembourser ou annuler le paiement dans le Merchant Portal de Worldline, ou à rétablir la commande manuellement. Le client qui revient voit Your payment was received after this order had been cancelled. Please contact us — we will restore the order or refund the payment. Si un second paiement arrive pour une commande déjà payée, la commande n'est pas modifiée. Une note vous invite à rembourser ce second paiement dans le Merchant Portal de Worldline.

Bloc de paiement Worldline

La page de la commande affiche un bloc Worldline payment avec l'identifiant du paiement, la référence marchand, la page de paiement hébergée, le statut de la tentative, le montant débité et le montant remboursé, un badge Test environment pour les paiements de test, l'historique des remboursements et les Payment notes de la commande.

Remboursements

Dans le bloc Worldline payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Worldline. Confirmez la question Refund this amount through Worldline? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Le paiement doit être capturé. Vous devez disposer du droit de modifier les commandes ; l'accès aux pages des modules n'est pas nécessaire. Les remboursements sont effectués dans le montant et la devise débités par Worldline. Ainsi, après un écart de montant ou de devise, vous pouvez rembourser jusqu'à concurrence de ce que le client a réellement payé, et non le total de la commande. Le remboursement est toujours envoyé à l'environnement du paiement d'origine (test ou production) avec les identifiants de ce compte, qui doivent donc être renseignés. Un remboursement relancé après un délai d'attente n'est pas exécuté deux fois, et un seul remboursement d'une commande est traité à la fois. Si Worldline refuse le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement accepté est ajouté à l'historique des remboursements et aux notes, avec l'identifiant et le statut du remboursement Worldline. Un remboursement total passe la commande au statut Refunded. Un remboursement partiel ne modifie pas le statut.

Le module ne crée pas d'avoirs. Les boutons de remboursement standard de PrestaShop sur la page de la commande ne renvoient pas d'argent via Worldline.

Les changements de statut des remboursements provenant de Worldline arrivent par webhook, mettent à jour l'historique des remboursements et sont ajoutés aux notes. Les remboursements effectués dans le Merchant Portal ne modifient ni le statut de la commande ni ne créent d'avoirs. Mettez-les à jour manuellement si nécessaire.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Worldline Gateway est le premier bloc de Modules > Module Manager > VibeFox Worldline Gateway > Configure, au-dessus des réglages. 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-worldline 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, Worldline n'est pas proposé aux clients à la finalisation de la commande. 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 à la finalisation de la commande. 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, 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é 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

Worldline n'apparaît pas à la finalisation de la commande : vérifiez que la licence est active, que Enable/Disable est activé et que le mode actuel dispose d'un Merchant ID, d'un API Key ID et d'une Secret API Key : les champs de test en mode test, les champs de production en mode production. 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 webhook ne fonctionne pas. Dans le Merchant Portal du compte utilisé (test ou production), vérifiez que l'endpoint existe et que son URL est exactement celle affichée dans Endpoint URL, sans redirection. Vérifiez que le secret du webhook de ce compte se trouve dans le champ correspondant (Test Webhook Secret ou Live Webhook Secret) et que le champ de l'identifiant de la clé du webhook est vide ou correspond à la clé. La commande est aussi créée lorsque le client revient sur la boutique après avoir payé.

Si le webhook répond Webhook secret not configured : aucun secret de webhook n'est défini. Saisissez le secret du webhook dans les réglages. Worldline renouvelle le webhook.

Si le webhook répond Invalid signature : le secret du webhook appartient à un autre compte ou à une autre clé, ou l'identifiant de la clé du webhook ne correspond pas à la clé qui a envoyé le webhook. Vérifiez que les secrets de test et de production ne sont pas inversés.

Si le webhook répond Missing signature, Empty body ou Invalid JSON : la requête ne provient pas de Worldline sous la forme attendue, ou un proxy ou une redirection l'a modifiée. Vérifiez que l'URL répond sans redirection.

Si le webhook répond Ignored : le webhook provient d'un autre Merchant ID que celui des réglages de ce mode. Vérifiez Test Merchant ID (PSPID) ou Live Merchant ID (PSPID).

Si le webhook répond Retry later : 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é). Worldline renouvelle le webhook. Consultez le champ Log pour connaître la raison.

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

Si Test credentials ou Live credentials affiche une erreur : enregistrez d'abord les réglages, puis vérifiez que le Merchant ID, l'API Key ID et la Secret API Key proviennent du même compte, et que les valeurs de test figurent dans les champs de test et les valeurs de production dans les champs de production.

Le client voit une erreur lorsqu'il choisit Worldline : consultez le champ Log sur la page du module. Les erreurs sont journalisées même lorsque Logging est désactivé. Pour obtenir le détail complet des requêtes, activez Logging et réessayez.

Les paiements de test ne confirment pas un paiement réel : les tests et la production sont séparés. Basculez Test Mode sur le mode souhaité et utilisez les identifiants et le webhook de ce compte.

La commande est en Worldline payment on hold ou Awaiting Worldline capture après le paiement : lisez les notes du bloc Worldline payment (voir Statuts de commande). Soit Worldline n'a pas encore confirmé la capture (le webhook finalise la commande), soit le montant ou la devise payés différaient du panier.

Le remboursement échoue avec un message concernant l'environnement : le paiement a été effectué dans l'environnement de test ou de production, et les identifiants de cet environnement ne sont pas renseignés. Saisissez-les et réessayez.

Développeurs : le hook actionWlgHostedCheckoutData modifie la requête de la page de paiement hébergée avant son envoi, par exemple pour limiter les moyens de paiement affichés.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Worldline Gateway et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete Data 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 transactions et remboursements Worldline ainsi que les statuts de commande Awaiting Worldline capture et Worldline payment on hold sont toujours conservés, afin que les commandes payées auparavant puissent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

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