VibeFox ECPay 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 : nouveau dollar taïwanais (TWD). ECPay n'encaisse qu'en TWD, le mode de paiement n'est donc affiché que lorsque le panier du client est en TWD. Ajoutez TWD dans International > Localization > Currencies si votre boutique ne l'a pas. Les montants sont envoyés en TWD entiers, car ECPay n'accepte pas les décimales : les totaux du panier sont arrondis au dollar le plus proche. Utilisez 0 décimale pour les prix en TWD afin d'éviter les arrondis.
Compte ECPay : pour les paiements réels, vous avez besoin du MerchantID, du HashKey et du HashIV de votre compte marchand ECPay, disponibles dans le back-office marchand d'ECPay (vendor.ecpay.com.tw). Pour les tests, aucun compte ECPay n'est nécessaire.
Accès au site : votre boutique doit être accessible depuis Internet en HTTP/HTTPS sur le port 80/443, afin qu'ECPay puisse transmettre les notifications de paiement. Un pare-feu ou une authentification de base placé devant le site les bloque.
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 ECPay Payment Gateway dans la liste des modules et cliquez sur Configure.
3. Saisissez votre clé de licence VibeFox dans License key du bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).
4. Activez Enable/Disable, choisissez les méthodes de paiement et laissez Test Mode activé pour vos premiers tests. Cliquez sur Save.
5. Pour les paiements réels, saisissez le Merchant ID, le Hash Key et le Hash IV (voir Configuration), désactivez Test Mode et cliquez sur Save.
À l'installation, le module crée deux statuts de commande : Awaiting ECPay payment et ECPay 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 ; TWD doit rester autorisé pour le module.
Configuration
Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox ECPay Payment Gateway > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche une erreur si votre boutique n'a pas de devise TWD (ECPay n'est alors pas proposé au tunnel de commande), ou un avertissement si la devise par défaut n'est pas TWD (ECPay n'est alors proposé qu'aux clients qui paient en TWD). Elle affiche une erreur si le mode réel n'a pas de MerchantID, de HashKey et de HashIV. Tant que le mode test est activé, elle avertit que les paiements sont envoyés au sandbox ECPay avec le marchand de test public 3002607, qu'aucun argent n'est encaissé, et que toute personne connaissant les clés sandbox publiques pourrait confirmer des commandes de test ; le mode test doit donc être désactivé avant d'accepter de vraies commandes.
ECPay (綠界)
Enable/Disable : Enable ECPay Payment active ou désactive le mode de paiement. Par défaut : désactivé.
Title : le nom du mode de paiement que voient les clients au tunnel de commande. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : ECPay (綠界). Obligatoire : la page ne s'enregistre pas avec un titre vide.
Description : le texte affiché sous le mode de paiement au tunnel de commande. Par défaut : Pay securely via ECPay (Credit Card, ATM, CVS, Barcode).
Compte ECPay
Retrouvez votre MerchantID, votre HashKey et votre HashIV dans le back-office marchand d'ECPay (vendor.ecpay.com.tw), sous System development management > System integration settings (系統開發管理 > 系統介接設定).
Test Mode : envoie les paiements au sandbox ECPay (payment-stage.ecpay.com.tw) avec le marchand de test public d'ECPay 3002607. Aucun argent réel. Les identifiants ci-dessous ne sont utilisés que lorsque le mode test est désactivé. Par défaut : activé. Tant qu'il est activé, les clients voient TEST MODE — ECPay sandbox, no real money is charged. sous le mode de paiement.
Merchant ID : votre Merchant ID ECPay (production). Ignoré en mode test.
Hash Key : votre Hash Key ECPay (production). Ignoré en mode test.
Hash IV : votre Hash IV ECPay (production). Ignoré en mode test.
Les espaces et sauts de ligne dans les identifiants copiés cassent toutes les signatures ; ils sont donc supprimés à l'enregistrement, et la page vous en informe. Un Hash Key et un Hash IV enregistrés ne sont plus jamais affichés : le champ reste vide et indique Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.
Clear saved secrets : cochez Hash Key ou Hash IV et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.
Options de paiement
Enabled Payment Methods : les modes de paiement proposés aux clients. Avec plusieurs modes, le client choisit au tunnel de commande. Les commandes ATM, CVS et code-barres restent en Awaiting ECPay payment jusqu'au paiement du client. Au moins un mode doit être sélectionné ; si aucun ne l'est, Credit Card est activé et la page vous en informe. Par défaut : Credit Card.
Default Payment Method : le mode présélectionné. Il doit faire partie des modes activés ; sinon, le premier mode activé est utilisé. Par défaut : Credit Card.
Order Prefix : le préfixe du numéro de transaction ECPay (MerchantTradeNo), jusqu'à 5 lettres ou chiffres. Les autres caractères sont supprimés à l'enregistrement, avec un message. Utile lorsque plusieurs boutiques partagent un même compte ECPay : donnez à chacune son propre préfixe. Par défaut : EC.
Notifications de paiement
ECPay transmet les résultats des paiements à votre boutique. Cette section affiche l'Notification URL. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_ecpay_payment_gateway/notify, éventuellement avec un code de langue comme /en/. Cette URL est envoyée avec chaque paiement : rien n'est à configurer dans ECPay, mais elle doit être accessible depuis Internet sur le port 80/443, sans pare-feu ni authentification de base devant. Le mode maintenance et la restriction par pays de votre boutique ne la bloquent pas.
Chaque notification est vérifiée par sa signature CheckMacValue, avec les clés de l'environnement (test ou réel) dans lequel le paiement a été lancé, et par le MerchantID de ce paiement. Les notifications sans signature valide sont rejetées, et ECPay les renvoie. Sans la notification, aucune commande n'est créée ; vérifiez le paiement dans le back-office ECPay.
Avancé
Enable Logging : écrit les ID de commande, les numéros de transaction, les montants et les codes retour ECPay dans logs/ecpay_p_debug.log.php, dans le dossier du module. Ce fichier ne peut pas être ouvert depuis le web. Aucune clé ni donnée client n'est journalisée. Les erreurs sont toujours journalisées, même si ce commutateur est désactivé. Par défaut : désactivé.
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 son journal. Les enregistrements de paiement ECPay et les statuts de commande sont toujours conservés, afin que les commandes existantes continuent de fonctionner après une réinstallation. Par défaut : désactivé.
Tunnel de commande
À l'étape de paiement, le client choisit le mode de paiement (par défaut ECPay (綠界)). Avec plusieurs modes activés, le client sélectionne aussi Credit Card, ATM (Virtual Account), CVS (Convenience Store) ou Barcode sous Payment Method.
Après confirmation, le client voit Redirecting to ECPay for payment. Please wait... et est redirigé vers la page de paiement ECPay, avec un bouton Proceed to ECPay si la redirection ne démarre pas. Le total du panier est envoyé en TWD entiers, avec les noms et quantités des produits. La page ECPay s'ouvre en chinois traditionnel pour les langues taïwanaise et hongkongaise, en chinois simplifié, en coréen ou en japonais pour ces langues, et en anglais pour toutes les autres, selon la langue de la boutique du client. Aucune commande n'existe encore à ce stade.
La commande n'est créée qu'après confirmation par ECPay au moyen d'une notification signée du serveur. Lorsque le client clique sur le lien de retour à la boutique sur la page ECPay et que la commande existe déjà, la page standard de confirmation de commande s'ouvre. Elle affiche Your ECPay payment has been received. pour une commande payée, Your ECPay payment was received and is being reviewed by the store. pour une commande mise en attente, et les instructions de paiement pour une commande ATM, CVS ou code-barres en attente. Si la notification n'est pas encore arrivée, une page Payment confirmation affiche We have not received a payment confirmation from ECPay for this order yet. Your order will be created as soon as ECPay confirms the payment. avec les boutons Check again et Back to checkout. Si ECPay signale l'échec du paiement, le client revient au tunnel de commande avec The payment was not completed. You can try again or choose another payment method. Le panier est conservé.
Pour ATM, CVS et code-barres, le client reçoit d'abord les coordonnées de paiement. La commande est créée en Awaiting ECPay payment, et le code banque et le compte virtuel, le code de paiement en magasin de proximité ou les codes-barres, le montant et la date Pay before sont affichés sous ECPay payment instructions sur la page de confirmation de commande et dans le détail de commande du client. Lorsque le client paie, ECPay envoie une nouvelle notification et la commande passe à payée. Les instructions de paiement ne sont pas ajoutées aux e-mails de PrestaShop.
Chaque tentative crée un nouveau numéro de transaction ECPay, car ECPay refuse les numéros réutilisés. Les nouvelles tentatives après un paiement échoué fonctionnent donc, et si le client revient en arrière dans le navigateur jusqu'à la page de redirection, une nouvelle tentative est lancée. Un panier peut compter jusqu'à 30 tentatives de paiement. Une fois que le panier a une commande, il ne peut plus être payé via le tunnel de commande ; une commande ATM ou CVS en attente se règle avec les coordonnées déjà émises.
Si le paiement ne peut pas être lancé, le client reste au tunnel de commande avec un bref message, par exemple The order total is too small for ECPay. lorsque le total est inférieur à 1 TWD après arrondi. Les limites de montant propres à ECPay pour chaque mode sont vérifiées sur la page ECPay, et non au tunnel de commande.
Le module ne prend que des paiements uniques sur la page ECPay. Il n'offre pas de remboursement depuis PrestaShop, ni de cartes enregistrées, ni d'abonnements ou de paiements périodiques (定期定額), ni de paiements échelonnés, Apple Pay, TWQR, WeChat Pay, BNPL, WebATM, factures électroniques ou logistique, et ne consulte pas le statut côté serveur : si votre boutique ne peut pas recevoir la notification, vérifiez le paiement dans le back-office ECPay.
Commandes
Statuts de commande
No order yet : le client a été envoyé vers ECPay et n'a pas encore payé, ou la notification n'est pas encore arrivée. Seul le panier existe.
Awaiting ECPay payment : le client a choisi ATM, CVS ou code-barres et a reçu les coordonnées de paiement. La note affiche le code banque et le compte virtuel, le code de paiement ou les codes-barres, ainsi que la date limite.
Payment accepted : le paiement a été confirmé. Il est enregistré avec le TradeNo ECPay comme ID de transaction, et une note affiche le TradeNo, le type de paiement, le montant et le numéro de transaction (avec une mention de mode test pour les paiements sandbox).
ECPay payment on hold : ECPay a signalé un montant ou une devise différent de celui du panier (par exemple, le panier a été modifié dans un autre onglet après le lancement du paiement), un paiement sandbox est arrivé après le passage en mode réel (aucun argent réel n'a été encaissé), ou le paiement est arrivé après l'annulation de la commande (le paiement est alors enregistré). La note l'explique. Comparez avec le back-office ECPay, puis traitez la commande ou remboursez le paiement là-bas.
Payment error : ECPay a signalé l'échec du dernier paiement ATM, CVS ou code-barres d'une commande en attente. La note affiche le code retour et le message d'ECPay.
Les notifications répétées sont ignorées. Une commande payée, remboursée ou annulée n'est jamais rouverte par un échec tardif. Un second paiement pour une commande déjà payée, par exemple depuis deux onglets du navigateur, est noté une seule fois, afin que vous puissiez le rembourser dans le back-office ECPay. Les paiements simulés lancés depuis le back-office ECPay sont seulement notés et ne marquent jamais une commande comme payée, car ECPay n'encaisse aucun argent pour eux.
Bloc de paiement ECPay
La page de commande affiche un bloc ECPay payment avec chaque tentative de paiement de la commande : le MerchantTradeNo avec un badge Test mode pour les tentatives sandbox, le mode, le montant en TWD, le statut, le TradeNo ECPay, le type de paiement et la date, ainsi que le code retour ECPay. En dessous figurent les ECPay notes de la commande. Pour une commande en ECPay payment on hold, le bloc vous rappelle de la comparer avec le back-office ECPay.
Remboursements
Les remboursements depuis PrestaShop ne sont pas disponibles. Remboursez le paiement dans le back-office ECPay, puis mettez la commande à jour manuellement dans PrestaShop. Les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d'argent via ECPay.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox ECPay Payment Gateway est le premier bloc de Modules > Module Manager > VibeFox ECPay Payment 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 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-ecpay 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-le dans votre compte vibefox.net.
Sans clé active, ECPay n'est pas proposé 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 vitrine de PrestaShop ne sait pas que vous êtes connecté au back-office : le mode 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 affectées : les paiements déjà lancés sont toujours confirmés.
Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement pendant que vous travaillez 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
ECPay n'apparaît pas au tunnel de commande : vérifiez que la licence est active, que Enable/Disable est activé, que le panier du client est en TWD et que, en mode réel, Merchant ID, Hash Key et Hash IV sont renseignés. La page de réglages affiche un message dans chacun de ces cas. Dans Payment > Preferences, vérifiez que le module est autorisé pour TWD, pour le pays du client et pour le groupe du client.
Le paiement a abouti, mais aucune commande n'a été créée : la notification ECPay n'a pas atteint votre boutique (site arrêté, pare-feu, authentification de base). ECPay réessaie plusieurs fois. Vous pouvez aussi vérifier la transaction dans le back-office ECPay. Activez Enable Logging pour voir les notifications reçues par le module ; les notifications rejetées sont de toute façon journalisées comme erreurs.
La notification répond 0|CheckMacValue verification failed : le Hash Key ou le Hash IV ne correspond pas à votre compte ECPay, ou le paiement a été lancé dans l'autre environnement. Recopiez-les depuis le back-office ECPay.
La notification répond 0|MerchantID mismatch : la notification appartient à un autre marchand ECPay que celui avec lequel le paiement a été lancé.
La notification répond 0|Order not found : le numéro de transaction n'a pas été émis par cette boutique, par exemple lorsque plusieurs boutiques partagent un même compte ECPay. Donnez à chaque boutique son propre Order Prefix.
La notification répond 0|Retry : le panier était en cours de traitement 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é). ECPay renvoie la notification. Activez Enable Logging pour voir la raison.
L'URL de notification affiche 0|Method not allowed in the browser : c'est normal. Cette URL n'accepte que les requêtes provenant d'ECPay.
Le client voit « The order total is too small for ECPay. » : le total du panier est inférieur à 1 TWD après arrondi et ne peut pas être payé avec ECPay.
Le client voit « Too many payment attempts for this order » : le panier a atteint 30 tentatives de paiement. Demandez au client de commencer un nouveau panier.
La commande est en ECPay payment on hold : lisez les notes du bloc ECPay payment (voir Statuts de commande), comparez-les avec le back-office ECPay, puis traitez la commande ou remboursez le paiement là-bas.
Développeurs : le hook actionEcpayPRequestParams permet à un autre module de modifier les paramètres envoyés à ECPay ; le marchand, le numéro de transaction et le montant ne peuvent pas être modifiés par ce biais.
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox ECPay Payment 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 enregistrements de paiement ECPay et les statuts de commande Awaiting ECPay payment et ECPay payment on hold sont toujours conservés, afin que les notifications tardives de paiements anciens soient toujours vérifiées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.
ECPay est une marque déposée de son propriétaire respectif. Ce module n'est ni affilié à ECPay ni approuvé par ECPay.