VibeFox TrustPay 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.
Compte finby (TrustPay) : vous avez besoin d'un projet dans le Merchant Portal de finby, avec son ID de projet et sa clé secrète. Pour les paiements de test, vous avez besoin d'un projet de test (playground) distinct, avec son propre ID de projet et sa propre clé secrète. Aucune autre clé n'est nécessaire : la clé secrète sert à la fois à obtenir l'accès à l'API et à vérifier la signature des notifications de paiement.
URL de notification accessible : finby doit pouvoir joindre votre site depuis Internet. Un pare-feu, le mode maintenance ou la protection par mot de passe du site bloque les notifications de paiement.
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_trustpay_gateway dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Payments > TrustPay / finby, 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 l'ID de projet et la clé secrète de votre projet de production et, pour les tests, ceux de votre projet de test (voir Configuration).
6. Activez Enable / Disable et enregistrez. Effectuez un paiement de test avec Test mode activé, puis décochez Test mode pour encaisser de vrais paiements.
Lors de la mise à jour depuis la version 1.0, votre ID de projet et votre clé secrète sont conservés comme identifiants de production, et le mode test est désactivé. Vérifiez les réglages après la mise à jour.
Configuration
Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > TrustPay / finby. Au-dessus des champs, la page vous avertit lorsque la passerelle est activée mais que l'ID de projet ou la clé secrète du mode actuel est vide, et lorsque la devise de la boutique n'est pas prise en charge. Dans les deux cas, le moyen de paiement est masqué au moment du paiement. Dans la liste des moyens de paiement, la passerelle est signalée comme nécessitant une configuration tant que le mode actuel n'a pas son ID de projet et sa clé secrète.
Général
Enable / Disable : Enable TrustPay / finby card payments active ou désactive le moyen de paiement. Par défaut : désactivé.
Title : le nom du moyen de paiement que voit le client au moment du paiement. Par défaut : Card payment (TrustPay).
Description : le texte affiché sous le moyen de paiement au moment du paiement. Par défaut : Pay securely by card on the TrustPay / finby payment page.
Identifiants API
Copiez l'ID de projet et la clé secrète de votre projet depuis le Merchant Portal de finby (TrustPay). La section contient un lien vers le Merchant Portal. Les paiements de test utilisent un projet de test (playground) distinct, avec son propre ID de projet et sa propre clé secrète. Aucun argent réel n'y est débité.
Test mode : Use the test project (no real payments). Les nouveaux paiements et remboursements utilisent les identifiants de test. Les remboursements d'une commande sont toujours effectués sur le projet par lequel la commande a été payée. Par défaut : activé.
Live Project ID : l'ID numérique de votre projet de production.
Live Secret key : la clé secrète du projet de production. Elle sert à obtenir les jetons d'accès à l'API et à vérifier les notifications de paiement.
Test Project ID : l'ID numérique de votre projet de test (playground).
Test Secret key : la clé secrète du projet de test.
Un ID de projet ne doit contenir que des chiffres. Si vous enregistrez une autre valeur, la page affiche une erreur et l'ancienne valeur est conservée. Les clés secrètes sont enregistrées exactement telles que saisies ; seuls les espaces au début et à la fin sont supprimés.
Notifications de paiement
La commande n'est marquée payée qu'après que finby a confirmé le paiement par une notification signée. L'extension envoie automatiquement l'URL de notification avec chaque paiement, vous n'avez donc rien à configurer. La section affiche l'URL, par exemple https://your-site/wc-api/trustpay_payment_callback/. Vous pouvez aussi la saisir comme URL de notification de vos projets dans le Merchant Portal. Les notifications sans signature valide sont rejetées.
L'extension ne demande pas elle-même le statut du paiement à finby. Si une notification n'atteint pas votre site, la commande reste en Pending payment jusqu'à ce que finby la livre.
Avancé
Order status after payment : le statut de commande défini après un paiement réussi. Le statut est défini en une seule étape, pour que le client ne reçoive qu'un seul courriel.
Debug logging : Log API requests and notifications ajoute des détails au journal. Les erreurs sont toujours journalisées, même lorsque cette option est désactivée. Les journaux se trouvent dans WooCommerce > Status > Logs, source wcp_trustpay_gateway, et ne contiennent ni clés, ni jetons, ni données de carte, ni données clients. Par défaut : désactivé.
Delete data on uninstall : Remove the plugin settings and logs when the plugin is deleted (order data is kept). Par défaut : désactivé.
Paiement
Le client choisit le moyen de paiement (par défaut Card payment (TrustPay)) et passe la commande. En mode test, le paiement affiche Test mode: no real payment will be taken. sous la description.
Les paiements par carte nécessitent l'adresse de facturation. Si la rue, la ville, le code postal ou le pays manque, le client voit Please enter your billing address (street, city, postcode and country) — it is required for card payments.
L'extension crée une demande de paiement par carte chez finby pour le total de la commande, dans la devise de la commande. Le nom, l'adresse et l'adresse e-mail du client sont transmis pour 3-D Secure, et l'ID de commande est transmis comme référence. Le client est redirigé vers la page de paiement de finby et y paie par carte. La page s'ouvre dans la langue de votre boutique lorsque finby la prend en charge, sinon en anglais. Une note sur la commande affiche la demande de paiement, le montant et le projet (test ou production).
Après le paiement, le client revient sur la page de confirmation de commande de votre boutique, et le panier est vidé. La commande n'est marquée payée qu'après confirmation de finby par la notification signée. Le retour lui-même ne modifie jamais le statut du paiement.
Si le client annule sur la page de paiement, ou si la page de paiement renvoie une erreur, le client revient sur la page Pay for order avec le message The card payment was cancelled. You can try again or choose another payment method. ou The card payment was not completed. Please try again or choose another payment method. Une note est ajoutée à la commande. Le client peut payer à nouveau depuis cette page.
Si finby ne peut pas démarrer le paiement, le client voit We could not start the card payment. Please try again in a moment or choose another payment method. La raison technique est écrite dans le journal.
Devises : EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF et USD. Les montants en HUF sont transmis sans décimales. Sur la page Pay for order, la devise de la commande est vérifiée.
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 est fournie avec des traductions en anglais, slovaque et tchèque.
L'extension ne prend que les paiements par carte, sous forme d'achat en une seule étape sur la page de finby. Elle ne gère ni virements bancaires ni autres moyens de paiement finby, ni boutons Apple Pay ou Google Pay, ni cartes enregistrées, ni abonnements ou paiements récurrents, ni autorisation et capture séparées, ni interrogation du statut.
Commandes et remboursements
Statuts de commande
Pending payment : le client a été envoyé vers finby et n'a pas encore payé, ou la notification n'est pas encore arrivée.
Processing or Completed : finby a confirmé le paiement, et le montant et la devise correspondent à la demande de paiement et au total de la commande. Le statut suit Order status after payment. La note de commande affiche le montant, la demande de paiement et le projet. L'ID de transaction est l'ID de demande de paiement finby.
On hold : défini dans trois cas. Le paiement est encore en attente chez finby, et la commande attend le résultat final. Le paiement n'a été qu'autorisé, pas capturé : capturez-le ou annulez-le dans le Merchant Portal de finby, puis mettez la commande à jour. Ou le montant ou la devise payés diffère de la demande de paiement ou du total de la commande, par exemple parce que la commande a été modifiée après l'envoi du client vers la page de paiement : vérifiez le paiement avant l'expédition. La note de commande explique le cas.
Failed : finby a rejeté le dernier paiement de la commande. La note affiche la raison lorsque finby la transmet. Le client peut payer à nouveau depuis Pay for order.
Une commande annulée ou remboursée n'est jamais rouverte par un paiement tardif. Une note vous invite à rétablir la commande ou à rembourser le paiement dans le Merchant Portal. Si un second paiement arrive pour une commande déjà payée, la commande n'est pas modifiée et une note vous invite à rembourser le doublon dans le Merchant Portal. Les rétrofacturations (chargebacks) et litiges signalés par finby sont ajoutés en notes.
Remboursements
Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Card payment (TrustPay) (le bouton affiche votre Title). Les remboursements totaux et partiels sont pris en charge. Le remboursement est envoyé au projet par lequel la commande a été payée (test ou production), même si vous avez changé de mode depuis, donc l'ID de projet et la clé secrète de ce mode doivent être renseignés. Les remboursements en HUF doivent être des montants entiers.
Un remboursement n'est enregistré que lorsque finby l'accepte. Sinon, WooCommerce affiche TrustPay refused the refund: avec la raison, et aucun remboursement n'est créé. Un remboursement réussi est ajouté aux notes de la commande.
Les remboursements effectués dans le Merchant Portal de finby ne sont pas enregistrés comme remboursements WooCommerce. Si finby envoie une notification à leur sujet, elle est ajoutée en note de commande et le statut de la commande ne change pas.
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 > TrustPay / finby. 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 dans votre compte vibefox.net.
Sans clé active, le moyen de paiement n'est pas affiché aux clients au moment du paiement. Si un paiement est démarré malgré tout, le client voit This payment method is not available. Please choose another one. Les gestionnaires connectés de la boutique voient toujours le moyen de paiement, marqué (unlicensed — visible to admins only), afin que vous puissiez 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à démarré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
Card payment (TrustPay) 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 a son ID de projet et sa clé secrète : Test Project ID et Test Secret key en mode test, Live Project ID et Live Secret key en mode production. La devise de la boutique, ou la devise de la commande sur la page Pay for order, doit être l'une des devises prises en charge. La page des réglages affiche un avertissement dans les deux cas. Les développeurs peuvent modifier la liste des devises avec le filtre trustpay_p_supported_currencies.
Le paiement a abouti, mais la commande reste en Pending payment : la notification n'a pas atteint votre boutique. Vérifiez que https://your-site/wc-api/trustpay_payment_callback/ est accessible depuis Internet (pas de pare-feu, de mode maintenance ni de protection par mot de passe). finby renouvelle la notification. Consultez WooCommerce > Status > Logs, source wcp_trustpay_gateway.
Le journal affiche Notification rejected: invalid signature or unknown project : la notification provient d'un projet dont l'ID de projet ne figure pas dans les réglages, ou la clé secrète de ce projet est incorrecte. La boutique répond Invalid signature et la commande n'est pas modifiée. Vérifiez l'ID de projet et la clé secrète du mode dans lequel le paiement a été effectué.
Le journal affiche Notification ignored : la notification concerne une demande de paiement que cette boutique n'a pas créée pour cette commande, ou un projet autre que celui avec lequel le paiement a été démarré. La commande n'est pas modifiée.
La notification reçoit la réponse Busy, retry later : la commande était en cours de mise à jour par une autre notification au même moment. finby la renouvelle.
Le client voit We could not start the card payment : ouvrez le journal. Un ID de projet ou une clé secrète erroné donne un message indiquant que finby a rejeté les identifiants du projet. Vérifiez que les identifiants de test sont dans les champs de test et les identifiants de production dans les champs de production.
Le paiement par carte est temporairement indisponible : le client voit ce message lorsque le mode actuel n'a ni ID de projet ni clé secrète. Saisissez-les et enregistrez.
La commande est On hold avec une note de différence de montant ou de devise : la notification était authentique, mais le montant ou la devise payé diffère de la demande de paiement ou du total de la commande. Vérifiez le paiement dans le Merchant Portal avant l'expédition, puis exécutez la commande ou remboursez le paiement.
Le remboursement échoue avec un message concernant le projet : la commande a été payée via le projet de test ou de production, et l'ID de projet ou la clé secrète de ce mode n'est pas renseigné, ou un autre ID de projet est enregistré maintenant. Saisissez les identifiants de ce projet, ou remboursez le paiement dans le Merchant Portal de finby.
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 et 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
Désactiver 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, ainsi que les jetons d'accès API en cache, sont toujours supprimés. Les réglages de la passerelle et les journaux de l'extension (fichiers journaux, y compris les anciens fichiers archivés, et entrées de journal dans la base de données) ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les données de commande sont conservées : les commandes existantes gardent leurs notes de paiement, leurs ID de demande de paiement et leurs ID de transaction.
TrustPay et finby sont des marques déposées de leurs propriétaires respectifs. Cette extension n'est ni affiliée à TrustPay ou finby, ni approuvée par eux.