VibeFox Worldline for WooCommerce — Aide

Prérequis

WordPress : 6.0 ou ultérieur.

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

PHP : 8.0 ou ultérieur.

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, et d'une clé de webhook avec son secret. Tous ces éléments 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi transférer le dossier wcp_worldline_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Worldline (Ingenico) > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page des extensions.

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

5. Saisissez les identifiants de test, enregistrez les réglages et cliquez sur Test credentials.

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

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

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Worldline (Ingenico). Dans la liste des moyens de paiement, Worldline est signalé comme nécessitant une configuration tant que le mode actuel n'a pas de Merchant ID, d'API Key ID et de Secret API Key. Sur la page des réglages, les champs d'identifiants du mode non utilisé sont grisés.

General

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 voient les clients au moment de payer. Par défaut : Worldline.

Description : le texte affiché sous le moyen de paiement lors du paiement. Par défaut : Pay securely via Worldline.

Worldline Direct API

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

Test Mode : Enable test mode (pre-production environment, no real money) 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écochez-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 à cette 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 (production)

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 à cette 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.

Vérifier les identifiants

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 s'affiche à côté des boutons, 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 du point d'accès affichée dans cette section des réglages. Elle ressemble à https://your-site/wc-api/wlg_worldline_webhook/. Copiez l'URL exactement telle qu'elle apparaît dans les réglages : elle doit répondre sans redirection, vérifiez donc les préfixes de langue ainsi que les redirections forcées vers www ou https. Saisissez ensuite l'identifiant et le secret de la clé de webhook dans Test Webhook Key ID et Test Webhook Secret. Faites de même dans le compte de production avec les champs de production.

L'extension répond automatiquement à la requête de vérification du point d'accès de Worldline. Elle traite les événements de paiement (changements de statut de paiement) et les événements de remboursement (changements de statut de remboursement). Les autres événements sont acceptés puis ignorés. Les webhooks sans signature valide sont rejetés. Un webhook est aussi ignoré s'il provient d'un Merchant ID différent de celui du compte dont le secret a signé ce webhook. Sans webhook, une commande n'est confirmé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, téléversé dans le Merchant Portal, par exemple SimplifiedCustomPaymentPage. Laissez ce champ vide pour utiliser la page de paiement Worldline par défaut.

Order Status After Payment : le statut de la commande une fois que Worldline confirme le paiement capturé. Le statut est appliqué immédiatement, sans seconde modification. Les paiements sont toujours demandés en vente directe (autorisation et capture).

Logging : Enable debug logging écrit toutes les requêtes API et les webhooks dans WooCommerce > Status > Logs, source wcp_worldline_gateway. 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é.

Delete Data : Delete the plugin settings and logs when the plugin is deleted. La désactivation de l'extension ne supprime jamais rien. Les données de paiement enregistrées sur les commandes sont conservées, car elles sont nécessaires aux remboursements. Par défaut : désactivé.

Lors d'une mise à jour depuis la version 1.0, l'ancien jeu unique d'identifiants est transféré dans les champs de test ou de production, selon le mode utilisé par la boutique.

Paiement

Le client choisit le moyen de paiement (par défaut Worldline) et passe sa commande. L'extension crée une page de paiement hébergée Worldline pour le montant total de la commande, dans la devise de la commande, et envoie le client sur la page de paiement de Worldline. Là, le client paie par carte, par portefeuille ou par un autre moyen de paiement activé dans votre compte Worldline. Le nom, l'adresse, l'adresse e-mail et le téléphone de facturation sont transmis à Worldline, et la page de paiement s'ouvre dans la langue de votre boutique lorsque Worldline la prend en charge. Chaque tentative de paiement reçoit sa propre référence, composée de l'ID de la commande et d'une partie aléatoire.

Après le paiement, le client revient sur votre boutique. L'extension vérifie le 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 : par cette vérification du statut ou par un webhook signé. Le client voit alors la page de confirmation de commande.

Si le paiement n'a pas été effectué, le client est redirigé vers la page Pay for order avec un message :

Un client peut payer à nouveau une commande non payée depuis la page Pay for order. Si la tentative précédente a été payée entre-temps, le client est directement redirigé vers la page de 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 voit Payment error: Could not create checkout session. Please try again. et peut choisir un autre moyen de paiement. La raison est ajoutée aux notes de commande et au journal. Si les identifiants du mode actuel sont absents, le client voit This payment method is not available at the moment. Please choose another payment method.

Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).

L'extension accepte les paiements uniques en vente directe sur la page de Worldline. Elle 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 WooCommerce, ni surcharge, ni enregistrement automatique des webhooks.

Commandes et remboursements

Order statuses

Pending payment : le client a été redirigé vers Worldline et n'a pas encore payé, ou Worldline n'a pas encore confirmé le paiement. Une note affiche l'ID de la page de paiement hébergée, la référence et le mode (test ou production).

Processing or Completed : le paiement a été capturé. Le statut suit Order Status After Payment. La note de commande affiche le montant, l'ID de paiement Worldline et le mode de confirmation (webhook signé ou vérification du statut). L'ID de transaction de la commande correspond à l'ID de paiement Worldline.

On hold, waiting for capture : Worldline indique que le paiement est autorisé ou que la capture est demandée, mais pas encore capturée. La note de commande l'explique. La commande est automatiquement marquée comme payée 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.

On hold, held for manual review : le paiement ne correspond pas à la commande, par exemple si le montant ou la devise diffèrent (la commande a été modifiée après le début du paiement) ou si le paiement appartient à une autre tentative. La note affiche le montant payé, le total de la commande et la référence. Vérifiez la commande, puis traitez-la ou remboursez le paiement.

Failed : Worldline a refusé ou annulé le paiement de la dernière tentative, ou le client n'était pas éligible au moyen de paiement choisi.

Cancelled : la commande a été annulée par vous ou par le délai d'expiration de la réservation de stock de WooCommerce. Si un paiement arrive pour une commande annulée ou remboursée, la commande n'est pas rouverte. Une note vous demande de rembourser ou d'annuler le paiement dans le Merchant Portal de Worldline, ou de 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 à nouveau. Une note vous demande de rembourser ce second paiement dans le Merchant Portal de Worldline.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant puis cliquez sur Refund via Worldline (Ingenico). Les remboursements totaux et partiels sont pris en charge. Le paiement doit être capturé. 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. Si Worldline refuse le remboursement, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement accepté est ajouté aux notes de commande avec l'ID et le statut du remboursement Worldline.

Les changements de statut des remboursements arrivent de Worldline par webhook et sont ajoutés aux notes de commande. Les remboursements effectués dans le Merchant Portal ne sont pas enregistrés automatiquement comme remboursements WooCommerce. Si nécessaire, créez un remboursement manuel dans WooCommerce sans utiliser Refund via Worldline (Ingenico).

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 > Worldline (Ingenico). Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, ainsi que votre domaine. Utilisez Check now pour vérifier à nouveau le statut, 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 l'emplacement de domaine correspondant. Libérez-le dans votre compte vibefox.net.

Sans clé active, Worldline n'est pas proposé 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. Les gestionnaires de la boutique connectés voient toujours le moyen de paiement, marqué (unlicensed — visible to admins only), afin de pouvoir configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page des extensions et sur les pages WooCommerce. 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, l'extension continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Worldline n'apparaît pas au moment du paiement : 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 liste des paiements signale le moyen de paiement comme nécessitant une configuration lorsque ces éléments manquent.

Le paiement a abouti, mais la commande reste en Pending payment : le webhook ne fonctionne pas. Dans le Merchant Portal du compte utilisé (test ou production), vérifiez que le point d'accès existe et que son URL correspond exactement à celle affichée dans les réglages, 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 Webhook Key ID est vide ou correspond à la clé. La commande est aussi confirmée lorsque le client revient sur la boutique après avoir payé.

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 l'envoi du webhook.

Le webhook répond Invalid signature : le secret du webhook appartient à un autre compte ou à une autre clé, ou Webhook Key ID ne correspond pas à la clé qui a envoyé le webhook.

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.

Le webhook répond Ignored : le webhook provient d'un Merchant ID différent de celui indiqué dans les réglages de ce mode. Vérifiez Test Merchant ID (PSPID) ou Live Merchant ID (PSPID).

Le webhook répond Retry later : la commande était en cours de mise à jour par une autre requête au même moment. Worldline renouvelle l'envoi du webhook.

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 lors de la passation de la commande : ouvrez les notes de commande ou WooCommerce > Status > Logs, source wcp_worldline_gateway. Les erreurs sont journalisées même lorsque le journal de débogage est désactivé. Pour obtenir tous les détails des requêtes, activez Logging et recommencez.

Les paiements de test ne confirment pas une commande réelle : les environnements de test et de production sont séparés. Un webhook signé avec le secret de test ne confirme jamais une tentative de paiement en production, et inversement. Réglez Test Mode sur le mode souhaité et utilisez les identifiants et le webhook de ce compte.

La commande est On hold après le paiement : lisez la note de commande. Soit Worldline n'a pas encore confirmé la capture (c'est le webhook qui finalise la commande), soit le montant ou la devise payés ne correspondaient pas à la commande.

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 filtre wlg_hosted_checkout_data modifie la requête de page de paiement hébergée, par exemple pour limiter les moyens de paiement affichés, et wlg_gateway_icon modifie l'icône du moyen de paiement.

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, puis 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 statut 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 le statut de licence de cette extension sont toujours supprimés. Les réglages de la passerelle et les journaux ne sont supprimés que si Delete Data était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les données de paiement Worldline enregistrées sur les commandes sont toujours conservées, car elles sont nécessaires aux remboursements. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

Worldline est une marque déposée de son titulaire respectif. Cette extension n'est ni affiliée à Worldline ni approuvée par Worldline.