VibeFox Paytrail for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les anciennes versions de PHP.

Devise : EUR. Paytrail n'accepte que l'euro. Pour un panier dans une autre devise, le moyen de paiement est masqué dans le tunnel de commande. Les montants sont envoyés en centimes.

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

Compte Paytrail : vous avez besoin de votre identifiant marchand et de votre clé secrète, affichés dans le panneau marchand Paytrail (informations du compte ou de l'intégration). Pour les tests, aucun compte n'est nécessaire : le mode test utilise le compte de test public de Paytrail. Les moyens de paiement eux-mêmes s'activent dans votre compte Paytrail.

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 Paytrail Gateway dans la liste des modules et cliquez sur Configure.

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

4. Pour essayer le module d'abord, activez Test mode. Pour les paiements réels, désactivez-le et saisissez votre Merchant ID et votre Secret key. Aucune URL de callback n'est à configurer dans Paytrail.

5. Activez Enable/Disable et cliquez sur Save.

À l'installation, le module crée deux statuts de commande, Awaiting Paytrail payment et Paytrail payment on hold. PrestaShop propose un nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez le restreindre dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Paytrail Gateway > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche Test mode is active. Payments use the public Paytrail test account — no real money is charged. tant que le mode test est activé. En mode réel, elle vous avertit lorsque l'identifiant marchand ou la clé secrète manque, ou lorsque l'identifiant marchand est le compte de test public 375917. Elle vous avertit aussi lorsque la devise de la boutique n'est pas l'EUR. Dans tous ces cas, Paytrail n'est pas affiché dans le tunnel de commande.

À l'enregistrement, un identifiant marchand contenant autre chose que des chiffres n'est pas enregistré : l'erreur Paytrail merchant ID must contain digits only. The previous value was kept. s'affiche. Le champ Title ne peut pas être vide.

Paytrail

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

Title : le titre affiché aux clients pendant le paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Paytrail. Obligatoire.

Description : le texte affiché aux clients sous le moyen de paiement pendant le paiement. Par défaut : Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.

Identifiants API

Votre identifiant marchand et votre clé secrète sont affichés dans le panneau marchand Paytrail (informations du compte ou de l'intégration). La section renvoie vers le panneau marchand. Seuls les paiements en EUR sont pris en charge.

Test mode : utilise le compte de test public de Paytrail (identifiant marchand 375917) pour les nouveaux paiements, à la place de vos propres identifiants. Aucun argent réel n'est débité et aucune clé n'est nécessaire. Les clients voient Test mode: no real payment will be made. sous le moyen de paiement. La clé secrète du compte de test est publique : n'importe qui pourrait donc simuler un paiement effectué en mode test. Ne laissez jamais le mode test activé sur une boutique en production. Par défaut : off.

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

Secret key : votre clé secrète Paytrail. Utilisée lorsque le mode test est désactivé. La clé enregistrée n'est plus jamais affichée. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.

Clear saved secret key : cochez Secret key puis cliquez sur Save pour supprimer la clé enregistrée. Un champ vide conserve la valeur enregistrée.

Les callbacks et les remboursements utilisent toujours les identifiants du mode dans lequel le paiement a été effectué ; passer du test au réel ne casse donc pas les anciennes commandes.

Commandes

Callback URL : affiche l'URL à laquelle Paytrail confirme chaque paiement de serveur à serveur. Avec des URL simplifiées, elle ressemble à https://your-shop/module/wcp_paytrail_gateway/callback. Elle est envoyée avec chaque paiement : rien n'est à configurer dans le panneau Paytrail, mais la boutique doit être accessible depuis Internet.

Order status after payment : le statut d'une commande payée.

Les paiements en attente restent dans Awaiting Paytrail payment. Les écarts de montant et les autres problèmes vont toujours dans Paytrail payment on hold.

Avancé

Debug log : consigne les requêtes API et les callbacks dans logs/ptg_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les données personnelles et les clés ne sont pas consignées. Les erreurs et avertissements sont toujours consigné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 : lorsqu'elle est activée, la désinstallation du module supprime les réglages et le journal. Désactiver le module ne supprime jamais rien. Les données de transaction Paytrail des commandes sont toujours conservées, car les remboursements des anciennes commandes en ont besoin. Par défaut : off.

Tunnel de commande

À l'étape de paiement, le client choisit le moyen de paiement (par défaut Paytrail) et confirme. Le module crée un paiement Paytrail pour le total du panier en euros et y joint les lignes de commande : produits après règles de panier, livraison et emballage cadeau, chacun avec son taux de TVA à une décimale. Les lignes correspondent toujours au montant du paiement ; un écart d'arrondi est intégré à une ligne ou envoyé comme ligne Rounding. Les adresses de facturation et de livraison ne sont envoyées que lorsqu'elles sont complètes, et les valeurs trop longues sont tronquées aux limites de Paytrail. La langue de la page de paiement est le finnois, le suédois ou l'anglais, selon la langue du panier. Aucune commande n'existe encore à ce stade.

Le client est redirigé vers la page de paiement Paytrail, choisit un moyen de paiement activé pour votre compte Paytrail et paie. Paytrail confirme ensuite le paiement à deux reprises : il renvoie le client vers votre boutique et appelle l'URL de callback de serveur à serveur. Les deux sont acceptés uniquement avec une signature valide, créée avec les identifiants de cette tentative de paiement, et uniquement pour une tentative créée pour ce panier. Le montant payé est comparé au total du panier. La commande n'est marquée comme payée qu'après confirmation de Paytrail de cette manière. Le module gère les statuts Paytrail suivants :

Après un paiement réussi, le client voit la page standard de confirmation de commande avec Your Paytrail payment has been received. Pour un paiement en attente, la page affiche Your Paytrail payment is pending confirmation by the payment provider. The order is updated automatically — please do not pay again. Si le callback enregistre le paiement au même moment, une page Payment confirmation demande au client de ne pas payer à nouveau et propose un bouton Check again.

Après un paiement annulé ou échoué, le client revient au tunnel de commande avec 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. Le panier est conservé. Un retour qui ne peut pas être vérifié affiche Payment verification failed. et ne modifie rien.

Si Paytrail ne peut pas démarrer le paiement, le client reste dans le tunnel de commande avec un bref message, par exemple Could not connect to Paytrail. Please try again in a moment., Paytrail is temporarily unavailable. Please choose another payment method. (identifiants incorrects) ou Paytrail could not start the payment. Please check your billing details and try again, or choose another payment method. La raison technique est écrite dans le journal. Un total hors des limites de Paytrail affiche This order total cannot be paid with Paytrail. Please choose another payment method.

Un paiement Paytrail ne peut pas être annulé via l'API. Chaque nouvelle tentative pour le panier est un nouveau paiement Paytrail. Si le client paie aussi une ancienne page de paiement encore ouverte, le second paiement est signalé sur la commande comme doublon à rembourser.

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

Le client choisit le moyen de paiement sur la page de Paytrail, et non dans votre tunnel de commande. Le module ne gère ni tokenisation de carte ni cartes enregistrées, ni abonnements, ni shop-in-shop, ni activation manuelle des factures, ni rapports de règlement.

Commandes et remboursements

Statuts de commande

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

Payment accepted or Delivered : le paiement a été confirmé. Le statut suit Order status after payment. Le paiement est enregistré avec l'identifiant de transaction Paytrail, et une note indique la transaction, le moyen de paiement utilisé chez Paytrail et le montant.

Awaiting Paytrail payment : le paiement est en attente chez le prestataire (facture ou paiement différé). La commande passe au statut payé lorsque Paytrail confirme le paiement, ou à Payment error s'il échoue.

Paytrail payment on hold : le montant payé diffère du total de la commande (le montant réellement payé est enregistré), le paiement est arrivé après l'annulation de la commande, ou un paiement test a été reçu alors que la boutique est en production (aucun argent réel, rien n'est enregistré). La note explique la raison. Vérifiez la commande, puis traitez-la ou remboursez le paiement.

Payment error : un paiement en attente a échoué ou a été annulé.

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

Les callbacks répétés ou parallèles ne créent jamais de seconde commande ni de notes en double. Si une seconde tentative d'un panier déjà payé est réglée, la commande n'est pas modifiée ; une note Duplicate payment vous demande de la rembourser dans le panneau marchand Paytrail.

Bloc de paiement Paytrail

La page de commande affiche un bloc Paytrail payment avec l'identifiant de transaction, le mode (un badge TEST mode pour les paiements test), le moyen de paiement, le statut Paytrail, le montant payé et remboursé, le formulaire de remboursement, l'historique des remboursements, les tentatives de paiement du panier et les Paytrail notes de la commande.

Remboursements

Dans le bloc Paytrail payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif pour la note de commande, puis cliquez sur Refund via Paytrail. Confirmez la question Refund this amount through Paytrail? This cannot be undone. Les remboursements totaux et partiels sont pris en charge, uniquement au montant. Vous devez disposer du droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. Vous pouvez rembourser jusqu'au montant réellement encaissé par Paytrail : après un écart de montant, la limite est donc ce que le client a payé, et non le total de la commande. Le remboursement utilise les identifiants du mode dans lequel le paiement a été effectué ; pour un paiement réel, les identifiants réels doivent donc être renseignés. Les remboursements ne sont disponibles qu'une fois le paiement confirmé par Paytrail.

Si le moyen de paiement ne prend pas en charge les remboursements directs, le module lance automatiquement un remboursement par e-mail : Paytrail envoie un e-mail au client pour qu'il saisisse un compte bancaire. Cela nécessite l'adresse e-mail du client sur la commande. La note indique le type de remboursement lancé.

Un remboursement peut être finalisé immédiatement ou traité plus tard. La confirmation ultérieure de Paytrail est ajoutée sous forme de note. Si Paytrail n'a pas pu finaliser le remboursement, une note indique que l'argent n'a pas été restitué au client, et le remboursement ne compte plus comme effectué : remboursez le client par un autre moyen. Si Paytrail rejette le remboursement immédiatement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement total place la commande en 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 commande ne renvoient pas d'argent via Paytrail. Les remboursements effectués dans le panneau marchand Paytrail ne sont pas synchronisés vers PrestaShop.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Paytrail Gateway est le premier bloc de Modules > Module Manager > VibeFox Paytrail 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 de fin de validité de la licence et votre domaine) ainsi que 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. Sous ceux-ci figurent la ligne Product: presta-payment-paytrail 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, Paytrail n'est pas affiché aux clients dans le tunnel de commande. Si un paiement est lancé malgré tout, le client voit This payment method is not available. Please choose another one. La boutique 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 dans le tunnel de commande. Un rappel apparaît dans Modules > Module Manager, dans l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés par les callbacks et le retour du client, 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é à nouveau automatiquement pendant votre travail dans le back-office : une fois par jour pendant les 14 premiers jours suivant 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

Paytrail n'apparaît pas dans le tunnel de commande : vérifiez que la licence est active, que Enable/Disable est activé et que soit Test mode est activé, soit Merchant ID et Secret key sont renseignés (et non le compte de test public 375917). Vérifiez que la devise du panier est l'EUR. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client. La page des réglages affiche un avertissement en cas d'identifiants manquants ou de devise de boutique incorrecte.

Le paiement a été effectué, mais aucune commande n'a été créée : le callback ne parvient pas à votre boutique, et le client n'est pas revenu sur la boutique. La Callback URL affichée dans la section Commandes doit être accessible depuis Internet (pas d'authentification de base ni de pare-feu qui bloque).

Le callback ou le retour affiche Payment verification failed. : la signature est invalide, ou le paiement n'appartient pas à une tentative de paiement du panier. Rien n'est modifié. Vérifiez que la Secret key est correcte et qu'elle appartient au Merchant ID.

Le callback répond Temporarily unavailable : 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é). Paytrail rappelle. Consultez le champ Log pour connaître la raison.

Le client voit une erreur en choisissant Paytrail : consultez le champ Log sur la page du module. Par exemple, Paytrail API error (401) signifie que les identifiants sont incorrects. Activez Debug log pour plus de détails.

L'identifiant marchand n'est pas enregistré : il ne doit contenir que des chiffres. Copiez-le à nouveau depuis le panneau marchand Paytrail.

La commande est Paytrail payment on hold : lisez les notes dans le bloc Paytrail payment. La raison est un montant payé différent, un paiement après annulation ou un paiement test en mode réel.

Le remboursement échoue : lisez le message. This order has no confirmed Paytrail payment. Refund it manually. signifie qu'il n'y a aucun paiement Paytrail confirmé à rembourser. The live Paytrail credentials used for this payment are missing. Enter them in the Paytrail settings. signifie que le paiement a été effectué en mode réel et que les identifiants réels ne sont pas renseignés. Invalid refund amount: at most … signifie que le montant est supérieur à ce qui reste à rembourser. Si le moyen de paiement ne prend en charge que les remboursements par e-mail, la commande a besoin de l'adresse e-mail du client.

Hook pour développeurs : le hook actionWcpPaytrailPaymentRequest modifie la requête de paiement avant qu'elle soit signée et envoyée.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Paytrail Gateway 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é, les réglages 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 Paytrail ainsi que les statuts de commande Awaiting Paytrail payment et Paytrail 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.

Paytrail est une marque de son titulaire. Ce module n'est ni affilié à Paytrail, ni approuvé par lui.