VibeFox Paytrail 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 lui.

PHP: 8.0 ou ultérieur.

Devise de la boutique : EUR. Paytrail n'accepte que les euros. Pour toute autre devise, le mode de paiement est masqué sur la page de commande. Les montants sont envoyés en centimes.

Accès Internet à votre site : Paytrail confirme chaque paiement par un callback de serveur à serveur, votre site doit donc être accessible depuis Internet. Sans callback, les commandes sont tout de même confirmées lorsque le client revient de Paytrail.

Compte Paytrail : vous avez besoin de votre Merchant ID et de votre Secret key, indiqués dans le Merchant Panel Paytrail (détails du compte ou de l'intégration). Aucun compte n'est requis pour les tests : le mode test utilise le compte de test public de Paytrail. Les modes de paiement sont quant à eux activés dans votre compte Paytrail.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un 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 téléverser le dossier wcp_paytrail_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Paytrail > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page Extensions.

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

5. Pour essayer d'abord l'extension, cochez Test mode. Pour de vrais paiements, décochez-la et saisissez vos Merchant ID et Secret key. Aucune URL de callback n'a besoin d'être configurée dans Paytrail.

6. Activez Enable/Disable et enregistrez.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Paytrail. Au-dessus des champs, la page affiche Test mode is active. tant que le mode test est activé. En mode réel, elle vous avertit s'il manque le Merchant ID ou la Secret key, et elle vous avertit si la devise de la boutique n'est pas l'EUR. Dans ces deux cas, Paytrail n'est pas affiché sur la page de commande. Dans la liste des modes de paiement, Paytrail est indiqué comme nécessitant une configuration tant que le mode réel n'a pas d'identifiants.

Lors de l'enregistrement, un Merchant ID contenant d'autres caractères que des chiffres n'est pas enregistré : une erreur s'affiche et la valeur précédente est conservée.

General

Enable/Disable: Enable Paytrail active ou désactive le mode de paiement. Valeur par défaut : désactivé.

Title: le titre affiché aux clients lors de la commande. Valeur par défaut : Paytrail.

Description: le texte affiché aux clients lors de la commande. Valeur par défaut : Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.

API credentials

Votre Merchant ID et votre Secret key sont indiqués dans le Merchant Panel Paytrail (détails du compte ou de l'intégration). Seuls les paiements en EUR sont pris en charge.

Test mode: Use the Paytrail test account. Les nouveaux paiements utilisent le compte de test public de Paytrail (Merchant ID 375917) au lieu de vos propres identifiants. Aucun montant réel n'est débité. Les clients voient Test mode: no real payment will be made. sur la page de commande. La Secret key du compte de test étant publique, n'importe qui pourrait simuler un paiement pour une commande créée en mode test. Ne laissez jamais le mode test activé sur une boutique en production. Valeur par défaut : désactivé.

Merchant ID: votre Merchant ID Paytrail (chiffres uniquement). Utilisé lorsque le mode test est désactivé.

Secret key: votre Secret key Paytrail. Utilisée lorsque le mode test est désactivé.

Les callbacks et les remboursements utilisent toujours les identifiants du mode dans lequel le paiement a été effectué, le passage entre test et production ne perturbe donc pas les anciennes commandes.

Orders

Cette section présente l'URL de callback, qui ressemble à https://your-site/wc-api/ptg_paytrail/. Paytrail confirme chaque paiement de serveur à serveur sur cette URL. Elle est envoyée avec chaque paiement, vous n'avez donc rien à configurer dans le panneau Paytrail, mais le site doit être accessible depuis Internet.

Order status after payment: l'état d'une commande payée. L'état est défini en une seule étape, le client ne reçoit donc qu'une seule série d'e-mails.

Advanced

Debug log: Log API requests and callbacks. Écrit dans WooCommerce > Status > Logs, source wcp_paytrail_gateway, sans données personnelles ni clés. Les erreurs sont toujours journalisées. Valeur par défaut : désactivé.

Delete data on uninstall: Delete settings, logs and Paytrail order data when the plugin is deleted. La désactivation de l'extension ne supprime jamais rien. Sans les données de transaction Paytrail, le remboursement d'anciennes commandes n'est plus possible depuis WooCommerce. Valeur par défaut : désactivé.

Paiement

Le client choisit le mode de paiement (par défaut Paytrail) et valide sa commande. L'extension crée un paiement Paytrail pour le montant total de la commande en euros et lui transmet les lignes de la commande : produits, livraison et frais, chacun avec son taux de TVA à une décimale. La somme des lignes équivaut toujours au montant du paiement ; un écart d'arrondi est intégré dans une ligne ou envoyé sous la forme d'une ligne Rounding. Les adresses de facturation et de livraison ne sont transmises que lorsqu'elles sont complètes, et les valeurs trop longues sont raccourcies selon les limites de Paytrail. La langue de la page de paiement est le finlandais, le suédois ou l'anglais, en fonction de la langue du site.

Le client est redirigé vers la page de paiement Paytrail, choisit un mode de paiement activé pour votre compte Paytrail et effectue le règlement. Paytrail confirme ensuite le paiement par deux canaux : il renvoie le client vers votre boutique et appelle l'URL de callback de serveur à serveur. Les deux ne sont acceptés qu'avec une signature valide générée avec les identifiants de cette tentative de paiement, et seulement pour la tentative créée pour cette commande. Le montant payé est comparé au total de la commande. La commande n'est marquée payée qu'une fois que Paytrail l'a confirmée ainsi. L'extension prend en charge les états Paytrail suivants :

Après un paiement réussi, le client arrive sur la page de confirmation de commande. Après un paiement annulé ou ayant échoué, le client est redirigé vers la page Pay for order avec le message The Paytrail payment was cancelled or failed. You can try again or choose another payment method. Si le paiement n'est pas encore terminé, le message est The Paytrail payment has not been completed yet. You can try again or choose another payment method.

Si Paytrail ne peut pas initialiser le paiement, le client voit s'afficher un message court, par exemple Could not connect to Paytrail. Please try again in a moment., Paytrail is temporarily unavailable. Please choose another payment method. (mauvais identifiants) ou Paytrail could not start the payment. Please check your billing details and try again, or choose another payment method. La raison technique est ajoutée aux notes de commande et au journal. Les commandes dépassant le montant maximum autorisé par Paytrail ne peuvent pas être payées avec Paytrail.

Un paiement Paytrail ne peut pas être annulé via l'API. Si le client lance un nouveau paiement et règle ensuite également une page de paiement plus ancienne restée ouverte, le second paiement est signalé dans les notes de commande comme un doublon à rembourser.

Le mode de paiement fonctionne sur le paiement classique, sur le bloc Commande et sur la page Pay for order. Il est compatible avec le stockage haute performance des commandes de WooCommerce (HPOS).

Le client choisit son mode de paiement sur la page Paytrail, et non lors de la validation sur votre site. L'extension ne prend pas en charge la création de jetons de carte ni l'enregistrement des cartes, ni WooCommerce Subscriptions, ni le shop-in-shop, ni l'activation manuelle des factures, ni les rapports de règlement.

Commandes et remboursements

États des commandes

Pending payment: le paiement Paytrail a été créé et le client n'a pas encore payé. La note de commande indique l'ID de transaction Paytrail, le montant et le mode.

Processing or Completed: le paiement a été confirmé. L'état correspond à Order status after payment. La note de commande indique la transaction, le mode de paiement utilisé chez Paytrail et le montant. L'ID de transaction est l'identifiant de transaction Paytrail.

On hold: le paiement est en attente chez le prestataire (facture ou paiement différé), le montant payé diffère du montant de la commande, le paiement est arrivé après l'annulation de la commande, ou un paiement de test a été reçu alors que la boutique est en ligne (pas d'argent réel). La note de commande en explique la raison. Examinez la commande, puis traitez-la ou remboursez le paiement.

Failed: la dernière tentative de paiement a échoué ou a été annulée par le client. Le client peut payer à nouveau.

Les callbacks répétés ou simultanés ne créent jamais de doublons dans les notes, les déductions de stock ou les e-mails. Si une seconde tentative pour une commande déjà payée est validée, la commande n'est pas modifiée à nouveau ; une note Duplicate payment vous invite à la rembourser dans le Merchant Panel Paytrail.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Paytrail (le bouton affiche votre Title). Les remboursements totaux et partiels sont pris en charge, pour les montants uniquement (aucune ligne d'article de remboursement). Le bouton n'est disponible que pour les commandes disposant d'un paiement Paytrail confirmé. Le remboursement utilise les identifiants du mode dans lequel le paiement a été effectué, des identifiants en ligne doivent donc être définis pour un paiement réel.

Si le mode de paiement ne permet pas les remboursements directs, l'extension déclenche automatiquement un remboursement par e-mail : Paytrail envoie un e-mail au client pour qu'il saisisse ses coordonnées bancaires. Cela nécessite une adresse e-mail de facturation sur la commande. La note de commande précise quel type de remboursement a été initié.

Un remboursement peut être validé immédiatement ou traité ultérieurement. La confirmation ultérieure de Paytrail est enregistrée sous forme de note. Si Paytrail n'a pas pu traiter le remboursement, une note indique que l'argent n'a pas été reversé au client : remboursez-le par un autre moyen et supprimez le remboursement dans WooCommerce. Si Paytrail refuse le remboursement d'emblée, WooCommerce signale l'erreur et aucun remboursement n'est enregistré.

Les remboursements effectués dans le Merchant Panel Paytrail ne sont pas synchronisés vers WooCommerce.

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 > Paytrail. 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 ainsi que votre domaine. Utilisez Check now pour vérifier à nouveau 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 domaine. Supprimer la clé d'un site ne libère pas son emplacement de domaine. Libérez l'emplacement depuis votre compte vibefox.net.

Sans clé active, Paytrail n'est pas proposé aux clients sur la page de commande. Si un paiement est lancé malgré tout, le client voit s'afficher This payment method is not available. Please choose another one. Les gestionnaires de la boutique connectés voient toujours le mode de paiement, avec la mention (unlicensed — visible to admins only), ce qui vous permet de configurer et tester l'extension avant d'acheter une clé. Un rappel s'affiche sur la page Extensions et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées : les paiements déjà commencés continuent d'être confirmés et les remboursements fonctionnent.

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

Dépannage

Paytrail n'apparaît pas sur la page de commande : vérifiez que la licence est active, que Enable/Disable est activé et que Test mode est activé ou que Merchant ID et Secret key sont renseignés. Vérifiez que la devise de la boutique (ou la devise de la commande sur la page Pay for order) est bien l'EUR. La page des réglages affiche un avertissement pour chacun de ces problèmes.

Le paiement est passé, mais la commande reste sur Pending payment : le callback ne parvient pas à joindre votre site et le client n'est pas revenu sur la boutique. L'URL de callback affichée dans la section Orders doit être accessible depuis Internet (sans mode de maintenance, authentification de base HTTP ni pare-feu bloquant).

Le callback ou le retour répond Payment verification failed. : la signature est invalide ou le paiement ne correspond pas à une tentative de paiement associée à cette commande. La commande n'est pas modifiée. Vérifiez que votre Secret key est correcte et correspond bien au Merchant ID.

Le paiement n'est pas créé : la note de commande et le journal indiquent l'erreur Paytrail, par exemple Paytrail API error (401): … en cas d'identifiants incorrects. Activez Debug log et consultez WooCommerce > Status > Logs, source wcp_paytrail_gateway.

Le Merchant ID n'est pas enregistré : il ne doit contenir que des chiffres. Copiez-le à nouveau depuis le Merchant Panel Paytrail.

La commande est sur On hold : lisez la note de commande. Cela s'explique par un paiement en attente ou différé, un montant payé différent, un paiement reçu après annulation ou un paiement de test reçu en production.

Le remboursement échoue : lisez le message. This order has no confirmed Paytrail payment. Refund it manually. indique qu'aucun paiement Paytrail confirmé ne peut être remboursé. Un message signalant des identifiants réels manquants signifie que le paiement a été effectué en mode réel et que les identifiants de production ne sont pas configurés. Si le mode de paiement ne prend en charge que les remboursements par e-mail, la commande requiert une adresse e-mail de facturation.

Crochets pour développeurs : le filtre ptg_payment_request modifie la requête de paiement avant qu'elle soit signée et transmise ; le filtre ptg_icon modifie l'icône sur la page de commande.

Le bloc de licence affiche une erreur : suivez les instructions du 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é sur le nouveau domaine. Si le serveur de licences est inaccessible, l'extension continue de fonctionner selon le dernier état connu.

Désinstallation

Désactiver l'extension conserve l'intégralité des données. Pour la retirer, désactivez-la et supprimez-la sur la page Plugins. La clé de licence et l'état de la licence de cette extension sont systématiquement supprimés. Les réglages de la passerelle, le journal de l'extension et les données Paytrail conservées sur les commandes (tentatives de paiement, données de transaction, enregistrements de remboursement) ne sont supprimés que si Delete data on uninstall était activé. Dans le cas contraire, ils restent enregistrés pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction ; sans les données Paytrail, les anciennes commandes ne peuvent plus être remboursées depuis WooCommerce.

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