VibeFox Tpay 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. L'extension OpenSSL et les connexions HTTPS sortantes vers secure.tpay.com sont nécessaires pour la vérification de la signature JWS des notifications.

Devise de la boutique : zloty polonais (PLN) uniquement. Tpay effectue les règlements en PLN et son Open API ne comporte pas de champ de devise ; le moyen de paiement est donc masqué lorsque le panier utilise une autre devise.

Accès à Internet pour votre boutique : Tpay envoie les notifications de paiement à votre boutique ; l'adresse de notification doit donc être accessible depuis Internet (non bloquée par un pare-feu ni par une authentification HTTP).

Compte Tpay : vous avez besoin de ces valeurs depuis le panneau marchand de Tpay : le Merchant ID (l'identifiant de votre compte Tpay), les clés Open API Client ID et Client secret (Integration, API) et le code de sécurité (Settings, Notifications). Les clés sandbox proviennent d'un compte sandbox Tpay distinct.

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 transfert terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Tpay Payment 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, et cliquez sur Activate (voir Clé de licence).

4. Saisissez les clés Sandbox et les clés Production (voir Configuration). Dans le panneau Tpay, seul le code de sécurité doit être renseigné : l'adresse de notification est envoyée avec chaque transaction.

5. Activez Enable/Disable et cliquez sur Save. Testez un paiement en mode sandbox, puis désactivez Sandbox mode pour accepter de vrais paiements.

À l'installation, le module crée le statut de commande Tpay 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 les limiter dans Payment > Preferences ; le PLN doit rester autorisé pour le module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Tpay Payment > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche Sandbox mode is on: payments go to the Tpay sandbox and no real money is charged. tant que le mode sandbox est activé. Elle vous avertit lorsque les clés du mode en cours sont incomplètes (Tpay n'est alors pas affiché au moment du paiement), lorsque la devise par défaut de la boutique n'est pas le PLN, et lorsque l'extension OpenSSL de PHP manque alors que la vérification JWS est activée (les paiements ne seraient alors pas confirmés). Les espaces collés avec le Merchant ID ou le Client ID sont supprimés à l'enregistrement.

Tpay

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

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

Description : la description du moyen de paiement affichée aux clients au moment du paiement. Par défaut : Pay with BLIK, online bank transfer or card on the secure Tpay page.

Sandbox mode : utilise le sandbox Tpay (paiements de test, sans argent réel) avec les clés Sandbox et openapi.sandbox.tpay.com. Désactivez-le pour accepter de vrais paiements avec les clés Production. Les remboursements sont toujours envoyés à l'environnement dans lequel la commande a été payée. Par défaut : activé.

Production keys

Où les trouver : dans le panneau marchand Tpay, sous Integration, API (clés Open API : Client ID et Secret) ; le Merchant ID est l'identifiant de votre compte Tpay ; le code de sécurité se trouve sous Settings, Notifications.

Merchant ID : l'identifiant de votre compte Tpay (chiffres). Tpay l'envoie dans chaque notification.

Client ID : le Client ID de l'Open API.

Client secret : le Client secret de l'Open API.

Security code : sert à vérifier la somme de contrôle MD5 des notifications Tpay.

Sandbox keys

Le sandbox est un compte de test Tpay distinct, avec ses propres clés (voir la documentation de l'API Tpay). Elles ne servent que lorsque Sandbox mode est activé.

Sandbox Merchant ID : le Merchant ID du compte sandbox.

Sandbox Client ID : le Client ID de l'Open API du compte sandbox.

Sandbox Client secret : le Client secret de l'Open API du compte sandbox.

Sandbox Security code : le code de sécurité des notifications du compte sandbox.

Les secrets enregistrés (Client secret et Security code des deux environnements) ne sont plus jamais affichés. Le champ reste vide et affiche Saved - leave empty to keep it. Saisissez une nouvelle valeur uniquement 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.

Payment notifications

Notification URL : Tpay confirme les paiements à l'adresse indiquée ici. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_tpay_payment/notify, éventuellement avec un code de langue comme /en/. L'adresse est envoyée automatiquement avec chaque transaction ; seul le code de sécurité doit être renseigné dans le panneau Tpay. Une commande n'est créée qu'après une notification dont la somme de contrôle et la signature sont valides et dont le montant correspond (ou après une vérification de statut correspondante lorsque le client revient). Tpay répète une notification jusqu'à ce que votre boutique l'accepte.

JWS signature : vérifie en outre la X-JWS-Signature des notifications avec le certificat Tpay (recommandé). Nécessite l'extension OpenSSL de PHP et les connexions HTTPS sortantes vers secure.tpay.com. Les certificats sont mis en cache pendant un jour. La somme de contrôle MD5 est toujours vérifiée. Par défaut : activé.

Advanced

Debug log : enregistre les événements de paiement : uniquement des événements techniques (sans clés ni données client) dans logs/wc_tp_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Par défaut : désactivé. Tant qu'il est désactivé, rien n'est écrit, erreurs comprises ; activez-le donc avant de chercher la cause d'un problème.

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

Delete data on uninstall : lorsqu'il est activé, la désinstallation du module supprime ses réglages et le journal. Les commandes et leurs données de paiement Tpay sont toujours conservées. Par défaut : désactivé.

Tunnel de commande

À l'étape du paiement, le client choisit le moyen de paiement (par défaut Tpay). En mode sandbox, l'option de paiement affiche Sandbox mode - no real money is charged. Après confirmation, le module crée une transaction Tpay pour le total du panier en PLN, avec la description Cart # et le numéro du panier, transmet le nom, l'e-mail, l'adresse de facturation et le téléphone du client, puis envoie le client sur la page de paiement Tpay. Cette page s'affiche en polonais, en anglais ou en ukrainien, selon la langue de la boutique (les autres langues reçoivent l'anglais). Le client y choisit BLIK, un virement bancaire, une carte ou un autre moyen activé sur votre compte Tpay, puis paie. Aucune commande n'existe encore à ce stade.

La commande n'est marquée payée qu'après la confirmation de Tpay. Tpay envoie une notification à votre boutique ; le module vérifie la somme de contrôle MD5 avec le code de sécurité, le Merchant ID et (si elle est activée) la signature JWS, en utilisant les clés de l'environnement dans lequel le paiement a été lancé, puis le montant : il doit être égal au montant demandé pour cette tentative de paiement et au total du panier, et le montant payé ne doit pas être inférieur. Les notifications sans somme de contrôle ou signature valide sont rejetées. La commande est ensuite créée et le client reçoit la page de confirmation de commande standard.

Après le paiement, le client revient dans votre boutique. Le simple retour ne marque rien comme payé. Si la notification n'est pas encore arrivée, le module interroge l'API Tpay sur le statut de la transaction (au maximum toutes les 10 secondes) et applique les mêmes contrôles. Tant que le paiement n'est pas confirmé, une page Payment confirmation affiche Tpay has not confirmed your payment yet. If you have paid, refresh this page in a moment. If the payment did not go through, you can try again: avec un bouton Refresh et un bouton Pay again qui ramène au tunnel de commande. La notification crée la commande dès son arrivée.

Si Tpay signale que le paiement a échoué, le client revient au tunnel de commande avec le message Tpay reports that the payment did not go through. Please try again or choose another payment method. Si le paiement échoue sur la page Tpay, Tpay renvoie le client vers la page du tunnel de commande. Le panier est conservé dans les deux cas. Si la commande a été mise en attente, la page de confirmation affiche Your payment is being verified. We will contact you as soon as it is confirmed.

Chaque tentative de paiement a sa propre référence. Lorsque le client paie à nouveau, les transactions Tpay précédentes non payées du panier sont annulées chez Tpay ; un paiement déjà effectué via un lien précédent reste accepté. Si le panier a déjà une commande, le client est dirigé vers la page de confirmation de cette commande au lieu d'un nouveau paiement.

Si Tpay ne peut pas démarrer le paiement, le client reste dans le tunnel de commande avec le message The Tpay payment could not be started. Please try again or choose another payment method. et la raison est enregistrée dans le journal (lorsque Debug log est activé).

L'adresse de notification fonctionne même lorsque la boutique est en mode maintenance et n'est pas bloquée par la restriction géographique de votre boutique.

Le module fonctionne uniquement en PLN. Il n'y a ni choix de banque ni saisie de code BLIK dans la boutique (le client choisit sur la page Tpay), ni cartes enregistrées, ni abonnements, ni boutons Apple Pay ou Google Pay dans la boutique, ni simulateurs de paiement échelonné.

Commandes et remboursements

Statuts de commande

No order yet : le client a été envoyé vers Tpay et n'a pas encore payé, ou Tpay n'a pas encore confirmé le paiement. Seul le panier existe. Un paiement échoué ne crée pas non plus de commande.

Payment accepted : Tpay a confirmé le paiement. Le paiement est enregistré avec le titre de la transaction Tpay (TR-...) comme identifiant de transaction. Une note indique s'il a été confirmé par la notification ou par la vérification du statut, l'environnement et l'éventuel trop-perçu.

Tpay payment on hold : un paiement est arrivé, mais son montant diffère du montant demandé ou du total du panier (par exemple, le panier a été modifié après le début du paiement), seule une partie a été payée, ou le paiement est arrivé après l'annulation de la commande. La note l'explique. Vérifiez le paiement dans le panneau Tpay, puis honorez la commande ou remboursez-la. Si le client paie ensuite le bon montant par une nouvelle tentative, la commande passe en Payment accepted.

Refunded : le paiement a été intégralement remboursé via le module.

Si Tpay signale un autre paiement pour une commande déjà payée ou remboursée, la commande n'est pas modifiée ; une note vous invite à rembourser le paiement en trop dans le panneau Tpay si nécessaire. Un litige (chargeback) signalé par Tpay ajoute une note.

Bloc de paiement Tpay

La page de commande affiche un bloc Tpay payment avec le titre et l'identifiant de la transaction Tpay, la référence du paiement (CRC), l'environnement (avec un badge Sandbox pour les paiements sandbox), le statut du paiement et la manière dont il a été confirmé, le montant payé, le total de la commande et le montant remboursé, l'historique des remboursements, toutes les Payment attempts du panier et les Payment notes de la commande.

Remboursements

Dans le bloc Tpay payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Tpay. Confirmez la question Refund this amount through Tpay? This cannot be undone. Les remboursements totaux et partiels sont pris en charge pour les commandes ayant un paiement reçu via Tpay, y compris les commandes mises en attente. 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 encaissé par la transaction Tpay ayant effectué le paiement, sans dépasser le total de la commande : après un paiement partiel ou un panier modifié, le bloc affiche Refundable (paid through Tpay). Le remboursement est envoyé à l'environnement (sandbox ou production) dans lequel la commande a été payée, les clés de cet environnement doivent donc être renseignées. Le remboursement n'est considéré comme effectué que lorsque Tpay le confirme ; un remboursement refusé ou non confirmé par Tpay est affiché comme une erreur et n'est pas enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec le motif que vous avez saisi (le motif n'est pas transmis à Tpay). Rembourser la totalité du montant remboursable passe 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 Tpay. Les remboursements effectués dans le panneau marchand Tpay ne sont pas ajoutés automatiquement à PrestaShop.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Tpay Payment est le premier bloc de Modules > Module Manager > VibeFox Tpay Payment > 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) 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. En dessous, se trouvent la ligne Product: presta-payment-tpay 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 : 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, Tpay n'est pas affiché 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. La vitrine PrestaShop ne sait pas que vous êtes connecté au back-office, donc le moyen de paiement est aussi masqué pour vous : 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, sous 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é à 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

Tpay n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable/Disable est activé et que les quatre clés du mode en cours sont saisies (Merchant ID, Client ID, Client secret, Security code). Vérifiez que la devise du panier est le PLN et que le module est autorisé pour le PLN, le pays du client et le groupe du client dans Payment > Preferences. La page de configuration affiche un avertissement pour les clés manquantes et pour une devise de boutique autre que le PLN.

Le paiement a été effectué, mais aucune commande n'a été créée : Tpay n'a pas pu remettre la notification ou elle a été rejetée. Activez Debug log et consultez le champ Log de la page du module. Les causes habituelles sont un code de sécurité ou un Merchant ID erroné pour l'environnement du paiement, une adresse de notification bloquée (pare-feu, authentification HTTP) ou un serveur sans OpenSSL ni HTTPS sortant pour la vérification JWS. La commande est aussi créée lorsque le client revient dans la boutique après avoir payé.

Notification answered FALSE - invalid checksum : le Merchant ID ou le code de sécurité des réglages ne correspond pas au compte Tpay (sandbox ou production) du paiement.

Notification answered FALSE - invalid JWS signature : la signature n'a pas pu être vérifiée, par exemple parce qu'OpenSSL est absent ou que le certificat Tpay ne peut pas être téléchargé. Corrigez le serveur ou, si nécessaire, désactivez JWS signature ; la somme de contrôle MD5 reste vérifiée.

Notification answered FALSE - busy, retry later or FALSE - order could not be created : le panier était en cours de traitement par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple parce que le module est désactivé). Tpay répète automatiquement la notification. Activez Debug log pour voir la raison.

L'URL de notification affiche FALSE - POST only in the browser : c'est normal. L'URL n'accepte que les notifications venant de Tpay.

La commande est en Tpay payment on hold : lisez les notes dans le bloc Tpay payment (voir Statuts de commande), vérifiez le paiement dans le panneau Tpay, puis honorez la commande ou remboursez le paiement.

Le client a vu The Tpay payment could not be started : les clés du mode en cours sont erronées ou Tpay a refusé la requête. Activez Debug log ; le journal affiche l'erreur Tpay.

Le client a vu We could not match this payment to an order : le lien de retour n'appartenait pas au panier du client. Si le client a été débité, la notification crée tout de même la commande ; vérifiez le panneau Tpay.

Le remboursement échoue : si le message indique que les clés sont manquantes, saisissez les clés de l'environnement dans lequel la commande a été payée. Si le message indique que le montant est trop élevé, seul le montant affiché peut être remboursé au maximum. Si Tpay n'a pas confirmé le remboursement, vérifiez la transaction dans le panneau marchand Tpay avant de réessayer.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Tpay Payment et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Les jetons d'accès Tpay et les certificats en cache sont toujours supprimés. Si Delete data on uninstall est activé, les réglages du module et le journal sont également supprimés. S'il est désactivé, les réglages sont conservés pour une réinstallation ultérieure. Les transactions et remboursements Tpay ainsi que le statut de commande Tpay payment on hold sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Tpay est une marque déposée de son titulaire. Ce module n'est ni affilié à Tpay ni approuvé par Tpay.