VibeFox Tpay for WooCommerce — Aide

Prérequis

WordPress : 5.8 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. 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 : uniquement le złoty polonais (PLN). Tpay règle en PLN et son Open API n'a pas de champ de devise ; le moyen de paiement est donc masqué lorsque la boutique (ou la commande à payer) utilise une autre devise.

Accès Internet à votre site : Tpay envoie les notifications de paiement à votre boutique ; l'adresse de notification doit donc être joignable depuis Internet (non bloquée par le mode maintenance, un pare-feu ou 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier wcp_tpay_payment dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

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

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

5. Saisissez les clés Sandbox et les clés de production (voir Configuration). Rien ne doit être configuré dans le panneau Tpay, sauf le code de sécurité : l'adresse de notification est envoyée avec chaque transaction.

6. Activez Enable/Disable, testez un paiement en mode sandbox, puis décochez Sandbox mode pour accepter de vrais paiements.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Tpay. 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 actuel sont incomplètes (Tpay n'est alors pas affiché au paiement), lorsque la devise de la boutique n'est pas le PLN, et lorsque l'extension PHP OpenSSL est absente alors que la vérification JWS est activée (les paiements ne seraient alors pas confirmés). Dans la liste des moyens de paiement, Tpay est indiqué comme nécessitant une configuration tant que les clés du mode actuel ne sont pas saisies. Les espaces collés avec le Merchant ID ou le Client ID sont supprimés à l'enregistrement.

Général

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. Par défaut : Tpay.

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 : Use the Tpay sandbox (test payments, no real money). Le mode sandbox utilise les clés Sandbox et l'API sandbox de Tpay. Désactivez-le pour accepter de vrais paiements avec les clés de production. Les remboursements sont toujours envoyés à l'environnement dans lequel la commande a été payée. Par défaut : activé.

Clés de production

Où les trouver : dans le panneau marchand de 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 dans Settings, Notifications.

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

Client ID : l'Open API Client ID.

Client secret : l'Open API Client secret.

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

Clés sandbox

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 : l'Open API Client ID du compte sandbox.

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

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

Notifications de paiement

Tpay confirme les paiements à l'adresse affichée dans cette section. Elle ressemble à https://your-site/wc-api/wc_tp_payment/. Cette adresse est envoyée automatiquement avec chaque transaction ; rien ne doit être configuré dans le panneau Tpay, sauf le code de sécurité. Une commande n'est marquée payée qu'après une notification dont la somme de contrôle et la signature sont valides et dont le montant correspond. Tpay répète une notification tant que votre boutique ne l'a pas acceptée.

Signature JWS : Also verify the X-JWS-Signature of notifications with the Tpay certificate (recommended). Nécessite l'extension PHP OpenSSL et des connexions HTTPS sortantes vers secure.tpay.com. La somme de contrôle MD5 est toujours vérifiée. Par défaut : activé.

Avancé

Debug log : Log payment events. Uniquement des événements techniques (sans clés ni données clients) dans WooCommerce > Status > Logs, source wcp_tpay_payment. Par défaut : désactivé.

Delete data on uninstall : Remove the plugin settings and logs when the plugin is deleted. La désactivation ne supprime jamais rien. Les commandes et leurs données de paiement Tpay sont toujours conservées. Par défaut : désactivé.

Les réglages de la version 1.0 sont repris automatiquement : les clés utilisées avec le mode test activé deviennent les clés Sandbox.

Paiement

Le client choisit le moyen de paiement (par défaut Tpay) et passe sa commande. En mode sandbox, la page de paiement affiche Sandbox mode — no real money is charged. L'extension crée une transaction Tpay pour le total de la commande en PLN, avec la description Order # suivie du numéro de commande, transmet le nom, l'adresse e-mail, l'adresse postale et le téléphone du client, puis redirige le client vers la page de paiement Tpay. Cette page s'affiche en polonais, en anglais ou en ukrainien, selon la langue du site (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.

La commande n'est marquée payée qu'après confirmation de Tpay. Tpay envoie une notification à votre boutique ; l'extension 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, puis le montant : il doit être égal au montant demandé pour cette tentative de paiement et au total de la commande, et le montant payé ne peut pas être inférieur. Les notifications sans somme de contrôle ou signature valide sont rejetées.

Après le paiement, le client revient sur la page de commande reçue. Le retour seul ne marque pas la commande comme payée. Si la notification n'est pas encore arrivée, la page interroge l'API Tpay pour connaître le statut de la transaction (au plus toutes les 10 secondes) et applique les mêmes contrôles. Tant que le paiement n'est pas confirmé, la page 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 lien Pay again. Lorsque Tpay signale un échec de paiement, la page affiche Tpay reports that the payment did not go through. You can try again: avec le même lien. Si le paiement échoue sur la page Tpay, Tpay renvoie le client vers la page Pay for order de la même commande.

Chaque tentative de paiement a sa propre référence. Lorsque le client paie à nouveau, les transactions Tpay précédentes non payées de la commande sont annulées chez Tpay ; un paiement déjà effectué via un lien précédent reste accepté. La même annulation a lieu lorsqu'une commande non payée est annulée, par exemple par le délai de réservation de stock de WooCommerce.

Si Tpay ne peut pas démarrer le paiement, le client voit The Tpay payment could not be started. Please try again or choose another payment method. et la raison est consignée dans le journal.

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 fonctionne uniquement en PLN. La boutique ne propose ni choix de banque ni code BLIK (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

Pending payment : la transaction Tpay a été créée et le paiement n'est pas encore confirmé. La note de commande affiche la transaction Tpay et l'environnement.

Processing : Tpay a confirmé le paiement. C'est le statut WooCommerce standard après paiement (les commandes ne contenant que des produits virtuels téléchargeables passent à Terminée). La note indique si le paiement a été confirmé par la notification ou par la vérification du statut, et affiche un éventuel trop-perçu. L'identifiant de transaction correspond au titre de la transaction Tpay (TR-...).

On hold : un paiement est arrivé, mais son montant différait du montant demandé ou du total de la commande, seule une partie a été payée, ou la commande avait été annulée. La note de commande l'explique. Vérifiez le paiement dans le panneau Tpay, puis finalisez ou remboursez la commande.

Failed : Tpay a signalé l'échec du paiement. Seule une commande en attente de paiement passe à Échec. Le client peut payer à nouveau.

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

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Tpay (le bouton affiche votre Title). Les remboursements totaux et partiels sont pris en charge pour les commandes ayant un paiement reçu via Tpay ; pour les commandes non payées, le bouton n'est pas affiché. 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é dans WooCommerce. Un remboursement réussi est ajouté aux notes de commande, avec le motif que vous avez saisi (le motif n'est pas envoyé à Tpay).

Les remboursements effectués dans le panneau marchand de Tpay ne sont pas ajoutés automatiquement à 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 > Tpay. 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 et 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. Libérez l'emplacement depuis 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. Les gestionnaires de la boutique connectés voient encore 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 Plugins 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 le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.

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 actuel sont saisies (Merchant ID, Client ID, Client secret, Security code). Vérifiez que la devise de la boutique (ou la devise de la commande sur la page Pay for order) est le PLN. La page des réglages affiche un avertissement pour chacun de ces problèmes.

Le paiement a abouti, mais la commande reste en Pending payment : Tpay n'a pas pu remettre la notification ou elle a été rejetée. Activez Debug log et consultez WooCommerce > Status > Logs, source wcp_tpay_payment. Les causes habituelles sont un code de sécurité ou un Merchant ID erroné pour le mode actuel, une adresse de notification bloquée (mode maintenance, pare-feu, authentification HTTP), ou un serveur sans OpenSSL ni connexion HTTPS sortante pour la vérification JWS. La page de commande reçue vérifie aussi le statut lorsque le client revient.

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.

La commande est On hold : lisez la note de commande. Le montant payé ne correspondait pas à la commande, ou le paiement est arrivé pour une commande annulée. Vérifiez le paiement dans le panneau Tpay, puis finalisez ou remboursez la commande.

Le client a vu The Tpay payment could not be started : les clés du mode actuel sont incorrectes ou Tpay a rejeté la demande. Le journal affiche l'erreur 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 Tpay n'a pas confirmé le remboursement, vérifiez la transaction dans le panneau marchand de Tpay avant de réessayer.

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, de même que les jetons d'accès Tpay et les certificats en cache. Les réglages de la passerelle et les journaux ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils sont conservés pour une future réinstallation. Les commandes existantes conservent leurs notes de paiement, leurs données de transaction Tpay et leurs identifiants de transaction.

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