VibeFox TrustPay 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.
Compte finby (TrustPay) : il vous faut un projet dans le Merchant Portal de finby, avec son ID de projet et sa clé secrète. Pour les paiements de test, il vous faut 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 boutique depuis Internet. Un pare-feu, une connexion de maintenance ou une authentification HTTP placée devant la boutique bloque les notifications de paiement.
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 TrustPay Gateway dans la liste des modules et cliquez sur Configure.
3. Saisissez votre clé de licence VibeFox dans le champ License key du bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).
4. Saisissez l'ID de projet et la clé secrète de votre projet de test et, pour les paiements réels, ceux de votre projet de production (voir Configuration).
5. Activez Enable / Disable et cliquez sur Save. Effectuez un paiement de test avec Test mode activé, puis désactivez Test mode pour encaisser de vrais paiements.
À l'installation, le module crée deux statuts de commande, Awaiting TrustPay payment et TrustPay payment on hold. PrestaShop associe un nouveau module de paiement aux pays actifs au moment de l'installation. Pour les pays que vous ajoutez plus tard, cochez le module dans Payment > Preferences. Vous pouvez également y limiter le module par devise et par groupe de clients.
Configuration
Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox TrustPay Gateway > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit lorsque le module est activé alors que l'ID de projet ou la clé secrète du mode actuel est vide, et lorsque la devise par défaut de la boutique n'est pas prise en charge. Dans les deux cas, le moyen de paiement est masqué au tunnel de commande.
TrustPay / finby
Enable / Disable : Enable TrustPay / finby card payments active ou désactive le moyen de paiement. Par défaut : off.
Title : le nom du moyen de paiement que voient les clients au tunnel de commande. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Card payment (TrustPay). Obligatoire.
Description : le texte affiché sous le moyen de paiement au tunnel de commande. Par défaut : Pay securely by card on the TrustPay / finby payment page.
Identifiants de l'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 : utilise le projet de test (aucun paiement réel). 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 : on. Tant qu'il est activé, les clients voient Test mode: no real payment will be taken. sous le moyen de paiement.
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 must contain digits only — the previous value was kept. et les autres champs sont enregistrés. Les clés secrètes sont enregistrées exactement telles que vous les saisissez ; seuls les espaces en début et en fin sont supprimés. Une clé secrète 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 si vous voulez la modifier. L'enregistrement des réglages supprime aussi les jetons d'accès à l'API en cache, afin que les nouveaux identifiants soient utilisés immédiatement.
Clear saved secrets : cochez une clé secrète et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.
Notifications de paiement
La commande n'est marquée payée qu'après que finby l'a confirmée par une notification signée. Le module envoie automatiquement l'URL de notification avec chaque paiement, vous n'avez donc rien à configurer. La section affiche l'URL sous Notification URL. Avec les URL simplifiées, elle ressemble à https://your-shop/module/wcp_trustpay_gateway/callback, éventuellement avec un code de langue. Vous pouvez aussi la saisir comme URL de notification de vos projets dans le Merchant Portal. Les notifications sans signature valide sont rejetées.
Le module ne demande pas lui-même à finby le statut du paiement. Si une notification ne parvient pas à votre boutique, aucune commande n'est créée tant que finby ne la remet pas. finby renouvelle les notifications.
Avancé
Order status after payment : le statut de commande appliqué après un paiement réussi. Le statut est défini en une seule étape, afin que le client ne reçoive qu'un seul courriel.
Debug logging : ajoute les requêtes API et les notifications dans logs/trustpay_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours journalisées, même lorsque cette option est désactivée. Le journal ne contient ni clés, ni jetons, ni données de carte, ni données clients. 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 du module et le journal. Les données de commande sont conservées : commandes, enregistrements de paiement TrustPay et remboursements, ainsi que les statuts de commande. Par défaut : off.
Tunnel de commande
À l'étape de paiement, le client choisit le moyen de paiement (par défaut Card payment (TrustPay)) et confirme la commande. Le moyen de paiement n'est proposé que dans les devises prises en charge : EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF et USD. Les montants en HUF sont envoyés sans décimales.
Les paiements par carte nécessitent une adresse. 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.
Le module crée auprès de finby une demande de paiement par carte pour le total du panier, dans la devise du panier. Le nom, l'adresse et l'e-mail du client sont transmis pour 3-D Secure, et le numéro de panier est envoyé comme référence. Aucune commande n'existe encore à ce stade. Le client est redirigé vers la page de paiement de finby et y paie par carte. La page s'ouvre dans la langue du panier lorsque finby la prend en charge, sinon en anglais.
Après le paiement, le client revient dans votre boutique. La commande n'est marquée payée qu'après que finby l'a confirmée par la notification signée. Le retour lui-même ne modifie jamais le statut du paiement. Si la notification est déjà arrivée, le client voit la page standard de confirmation de commande. Sinon, une page Payment confirmation indique que finby confirme le paiement par carte et que la commande sera créée dès cette confirmation. Elle comporte un bouton Check again et un bouton Back to checkout. Tant que la commande est en Awaiting TrustPay payment ou TrustPay payment on hold, la page de confirmation affiche Your card payment is being confirmed by TrustPay / finby. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Si finby a refusé le paiement ou si la commande non payée a été annulée, elle affiche Your card payment was not completed. Please contact us about this order.
Si le client annule sur la page de paiement, il revient au tunnel de commande avec le message The card payment was cancelled. You can try again or choose another payment method. Si la page de paiement renvoie une erreur, ou si finby a déjà refusé le paiement, le message est The card payment was not completed. Please try again or choose another payment method. Le panier est conservé et le client peut payer à nouveau.
Si finby ne peut pas démarrer le paiement, le client reste au tunnel de commande avec le message 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.
La notification fonctionne pendant que la boutique est en mode maintenance et n'est pas bloquée par la restriction géographique de votre boutique.
Le module n'accepte que les paiements par carte, en achat en une seule étape sur la page de finby. Il ne propose ni virements bancaires ni d'autres moyens de paiement finby, ni boutons Apple Pay ou Google Pay sur votre site, 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
No order yet : le client a été redirigé vers finby et n'a pas payé, ou la notification n'est pas encore arrivée. Seul le panier existe.
Payment accepted or Delivered : finby a confirmé le paiement, et le montant et la devise correspondent à la demande de paiement et au total du panier. Le statut suit Order status after payment. Le paiement est enregistré avec l'ID de la demande de paiement finby comme ID de transaction, et une note indique le montant, la demande de paiement et le projet (test ou production).
Awaiting TrustPay payment : finby a signalé que le dernier paiement est en attente. La commande passe au statut payé lorsque finby confirme le paiement.
TrustPay payment on hold : ce statut est attribué dans deux cas. Le paiement a seulement été autorisé, pas capturé : capturez-le ou annulez-le dans le Merchant Portal de finby, puis mettez la commande à jour. Ou bien le montant ou la devise payés ne correspondent pas à la demande de paiement ou au total du panier, par exemple parce que le panier a été modifié après l'envoi du client vers la page de paiement : vérifiez le paiement avant l'expédition. La note explique le cas.
Payment error : finby a refusé le dernier paiement d'une commande en attente. La note indique la raison lorsque finby la transmet. Un paiement confirmé ensuite fait tout de même passer la commande au statut payé.
Refunded : le paiement a été entièrement remboursé par le module.
Une commande annulée ou remboursée n'est jamais rouverte par un paiement tardif. Une note vous demande de rétablir la commande ou de 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 demande de rembourser le doublon dans le Merchant Portal. Les rétrofacturations et litiges signalés par finby sont ajoutés comme notes.
Bloc de paiement TrustPay / finby
La page de commande affiche un bloc TrustPay / finby payment avec l'ID de la demande de paiement, l'ID du paiement finby, le projet, le statut du paiement, les montants demandé et payé, le montant remboursé, un badge Test project pour les paiements de test, l'historique des remboursements et les TrustPay notes de la commande.
Remboursements
Dans le bloc TrustPay / finby payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via TrustPay. Confirmez la question Refund this amount through TrustPay? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez avoir le droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. Les remboursements s'effectuent dans le montant et la devise que finby a indiqués pour le paiement. Ainsi, après un écart de montant, vous pouvez rembourser jusqu'au montant que le client a réellement payé, et non le total de la commande. Les remboursements en HUF doivent être des montants entiers.
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. Les ID de projet et clés secrètes de ce projet doivent être renseignés, et son ID de projet ne doit pas avoir changé. Un remboursement n'est enregistré que lorsque finby l'accepte. Sinon, le bloc affiche TrustPay refused the refund: avec la raison, et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes. 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 finby. Les remboursements effectués dans le Merchant Portal de finby ne sont pas enregistrés comme remboursements. Si finby envoie une notification à ce sujet, elle est ajoutée comme note et le statut de la commande ne change pas.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox TrustPay Gateway est le premier bloc de la page Modules > Module Manager > VibeFox TrustPay Gateway > Configure, au-dessus des réglages. Saisissez la clé dans License key puis 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 figurent la ligne Product: presta-payment-trustpay 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, le paiement par carte n'est pas affiché aux clients au tunnel de commande. Si un paiement est tout de même lancé, 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 au tunnel de commande. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas touchées : les paiements déjà démarrés sont toujours confirmés par la notification TrustPay et le retour vers la boutique, 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é automatiquement pendant votre travail dans le back-office : une fois par jour pendant les 14 premiers jours après 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
Card payment (TrustPay) n'apparaît pas au tunnel de commande : vérifiez que la licence est active, que Enable / Disable est activé et que le mode actuel dispose de son ID de projet et de 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 du panier doit faire partie des devises prises en charge. La page des réglages affiche un avertissement lorsque les identifiants manquent ou que la devise par défaut n'est pas prise en charge. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client.
Le paiement a abouti, mais aucune commande n'a été créée : la notification n'a pas atteint votre boutique. Vérifiez que l'URL affichée sous Notification URL est accessible depuis Internet (sans pare-feu, connexion de maintenance ni authentification HTTP). finby renouvelle la notification, et la commande est créée à sa réception. Activez Debug logging et consultez le champ Log sur la page du module.
Le journal affiche Notification rejected: invalid signature or unknown project : la notification provient d'un projet dont l'ID de projet n'est pas dans les réglages, ou la clé secrète de ce projet est incorrecte. La boutique répond Invalid signature et rien n'est modifié. 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 ce panier, ou un autre projet ou mode que celui avec lequel le paiement a été lancé. Rien n'est modifié.
La notification reçoit la réponse Busy, retry later ou Temporary error : le panier était en cours de mise à jour par une autre notification au même moment, ou la commande n'a pas pu être créée (par exemple parce que le module est désactivé). finby renouvelle la notification. Le journal indique la raison.
Le client voit We could not start the card payment : ouvrez le journal. Un ID de projet ou une clé secrète incorrects donnent un message indiquant que finby a refusé 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.
Card payment is temporarily unavailable : le client voit ce message lorsque le mode actuel n'a pas d'ID de projet ni de clé secrète. Saisissez-les et enregistrez.
La commande est en TrustPay payment on hold : lisez les notes du bloc TrustPay / finby payment (voir Statuts de commande). Vérifiez le paiement dans le Merchant Portal avant l'expédition, puis traitez la commande ou remboursez le paiement.
Le remboursement échoue avec un message concernant le projet : la commande a été payée sur le projet de test ou de production, et l'ID de projet ou la clé secrète de ce mode ne sont pas renseignés, ou un autre ID de projet y est maintenant enregistré. Saisissez les identifiants de ce projet, ou remboursez le paiement dans le Merchant Portal de finby.
Invalid refund amount: at most … can be refunded : le montant est supérieur au montant payé moins les remboursements déjà effectués par le module.
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox TrustPay Gateway et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Les jetons d'accès à l'API en cache sont toujours supprimés. Si Delete data on uninstall est activé, les réglages du module 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 enregistrements de paiement TrustPay et les remboursements, ainsi que les statuts de commande Awaiting TrustPay payment et TrustPay payment on hold, sont toujours conservés : les commandes payées auparavant peuvent donc encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.
TrustPay et finby sont des marques de commerce de leurs titulaires respectifs. Ce module n'est ni affilié ni approuvé par TrustPay ou finby.