VibeFox ECPay for WooCommerce — Aide
Prérequis
WordPress : 6.0 ou ultérieur.
WooCommerce : 8.0 ou ultérieur, installé et actif.
PHP : 8.0 ou ultérieur.
Devise de la boutique : nouveau dollar taïwanais (TWD). ECPay facture uniquement en TWD, et la méthode de paiement est masquée lorsque la boutique, ou la commande en cours de paiement, utilise une autre devise. Les montants sont envoyés en TWD entiers, car ECPay n'accepte pas les décimales : les totaux de commande 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, de la HashKey et de la HashIV de votre compte marchand ECPay, depuis le back-office marchand ECPay (vendor.ecpay.com.tw). Pour les tests, aucun compte ECPay n'est nécessaire.
Accès au site : votre site doit être accessible depuis Internet en HTTP/HTTPS sur le port 80/443, afin qu'ECPay puisse délivrer les notifications de paiement. Un mode maintenance, un pare-feu ou une authentification de base devant le site les bloquent.
Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un 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 importer le dossier wcp_ecpay_payment_gateway dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate. WooCommerce doit être actif.
3. Ouvrez les réglages : WooCommerce > Settings > Payments > ECPay (綠界) > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page des extensions.
4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.
5. Activez Enable/Disable, choisissez les méthodes de paiement et laissez Test Mode activé pour vos premiers tests. Dans le sandbox, vous pouvez payer avec la carte de test ECPay 4311-9522-2222-2222 (toute date d'expiration future, CVV 222, code 3-D Secure depuis la page du sandbox).
6. Pour les paiements réels, saisissez le MerchantID, la HashKey et la HashIV (voir Configuration) et décochez Test Mode.
Configuration
Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > ECPay (綠界). Au-dessus des champs, la page affiche une erreur lorsque la devise de la boutique n'est pas le TWD (ECPay n'est alors pas affiché lors du paiement) et lorsque le mode production n'a pas de MerchantID, de HashKey ni 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 publiques du sandbox pourrait confirmer des commandes de test ; le mode test doit donc être désactivé avant d'accepter des commandes réelles.
Général
Enable/Disable: Enable ECPay Payment active ou désactive la méthode de paiement. Par défaut : désactivé.
Title: le nom de la méthode de paiement que voient les clients lors du paiement. Par défaut : ECPay (綠界).
Description: le texte affiché sous la méthode de paiement lors du paiement. Par défaut : Pay securely via ECPay (Credit Card, ATM, CVS, Barcode).
Compte ECPay
Trouvez votre MerchantID, HashKey et HashIV dans le back-office marchand ECPay (vendor.ecpay.com.tw) sous System development management > System integration settings (系統開發管理 > 系統介接設定).
Test Mode: Enable sandbox/test mode envoie les paiements vers le sandbox ECPay (payment-stage.ecpay.com.tw) avec le marchand de test public ECPay 3002607. Pas d'argent réel. Les identifiants ci-dessous ne sont utilisés que lorsque le mode test est désactivé. Par défaut : activé.
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 retours à la ligne dans les identifiants collés cassent toutes les signatures, ils sont donc supprimés à l'enregistrement, et la page vous en informe.
Options de paiement
Enabled Payment Methods: les méthodes proposées aux clients. Avec plus d'une, le client choisit lors du paiement. Les commandes ATM, CVS et Barcode restent En attente jusqu'au paiement du client. Au moins une méthode doit être sélectionnée ; si aucune ne l'est, Credit Card est activée. Par défaut : Credit Card.
Default Payment Method: la méthode présélectionnée. Elle doit être l'une des méthodes activées ; sinon, la première méthode activée est utilisée. 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. Utile lorsque plusieurs boutiques partagent un même compte ECPay : donnez à chaque boutique son propre préfixe. Par défaut : EC.
Notifications de paiement
ECPay envoie les résultats de paiement à votre boutique. Cette section affiche l'URL de notification. Elle ressemble à https://your-site/wc-api/ecpay_p_callback/. L'URL est envoyée à chaque paiement, donc rien n'est à configurer dans ECPay, mais elle doit être accessible depuis Internet sur le port 80/443, sans mode maintenance, pare-feu ni authentification de base devant elle.
Chaque notification est vérifiée par sa signature CheckMacValue avec les clés de l'environnement (test ou production) dans lequel le paiement a été lancé. Les notifications sans signature valide sont rejetées, et ECPay les renvoie. Sans la notification, aucune commande n'est marquée payée ; vérifiez le paiement dans le back-office ECPay.
Avancé
Enable Logging: Log payment events and API calls écrit les identifiants de commande, numéros de transaction, montants et codes de retour ECPay dans WooCommerce > Status > Logs, source wcp_ecpay_payment_gateway. Aucune clé ni donnée client n'est journalisée. Par défaut : désactivé.
Delete Data on Uninstall: Delete all plugin data when uninstalling. Supprime tous les réglages, journaux et métadonnées de commande de cette extension. Par défaut : désactivé.
Paiement
Le client choisit la méthode de paiement (par défaut ECPay (綠界)). Avec plusieurs méthodes activées, le client choisit aussi Credit Card, ATM (Virtual Account), CVS (Convenience Store) ou Barcode. Tant que le mode test est activé, la méthode de paiement affiche TEST MODE — ECPay sandbox, no real money is charged.
Une fois la commande passée, le client voit Redirecting to ECPay for payment. Please wait... et est envoyé vers la page de paiement ECPay, avec un bouton Proceed to ECPay au cas où la redirection ne démarrerait pas. Le total de la commande est envoyé en TWD entiers avec les noms et quantités des articles. La page ECPay s'ouvre en chinois traditionnel pour les langues de site taïwanais et de Hong Kong, en chinois simplifié, coréen ou japonais pour ces langues, et en anglais pour toutes les autres.
La commande n'est marquée payée qu'après confirmation d'ECPay par une notification serveur signée. Si le client revient sur la page de commande reçue avant l'arrivée de la confirmation, la page affiche We have not received a payment confirmation from ECPay for this order yet. If you did not complete the payment, you can try again: avec un bouton Pay.
Pour ATM, CVS et Barcode, le client reçoit d'abord les détails de paiement. La commande est mise En attente, et le code bancaire 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 remerciement, dans My account > Orders et dans l'e-mail de commande en attente. Lorsque le client paie, ECPay envoie une autre notification et la commande est marquée payée.
Chaque visite de la page de paiement crée un nouveau numéro de transaction ECPay, car ECPay rejette les numéros réutilisés. Ainsi, la page Pay for order et les nouvelles tentatives après un paiement échoué fonctionnent, et les notifications pour l'un de ces numéros sont associées à la commande. Une commande peut compter jusqu'à 30 tentatives de paiement.
Les propres limites de montant d'ECPay par méthode, par exemple pour les paiements en magasin de proximité, sont vérifiées sur la page ECPay, pas lors du paiement.
La méthode de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Elle est compatible avec WooCommerce High-Performance Order Storage (HPOS).
L'extension ne prend que les paiements uniques sur la page ECPay. Elle ne gère ni remboursements depuis WooCommerce, ni cartes enregistrées, ni abonnements ou paiements périodiques (定期定額), ni paiements échelonnés, Apple Pay, TWQR, WeChat Pay, BNPL, WebATM, factures électroniques ou logistique, ni interrogation de statut côté serveur : si votre site ne peut pas recevoir la notification, vérifiez le paiement dans le back-office ECPay.
Commandes
Statuts de commande
Pending payment: le client a été envoyé vers ECPay et n'a pas encore payé, ou la notification n'est pas encore arrivée.
On hold, waiting for payment: le client a choisi ATM, CVS ou Barcode et a reçu les détails de paiement. La note de commande affiche le code bancaire et le compte virtuel, le code de paiement ou les codes-barres et la date limite.
Processing: le paiement a été confirmé (valeur par défaut de WooCommerce ; les commandes contenant uniquement des produits téléchargeables virtuels passent à Terminée). La note de commande affiche le TradeNo ECPay, le type de paiement, le montant et le numéro de transaction. L'identifiant de transaction est le TradeNo ECPay.
On hold after payment: ECPay a signalé un montant ou une devise différents de la commande, un paiement sandbox est arrivé après votre passage en mode production (aucun argent réel n'a été encaissé), ou le paiement est arrivé après l'annulation de la commande. La note de commande l'explique. Comparez avec le back-office ECPay et finalisez ou remboursez la commande manuellement.
Failed: ECPay a signalé que la dernière tentative de paiement a échoué. La note affiche le code de retour et le message ECPay. Le client peut réessayer.
Les notifications répétées sont ignorées. Une commande payée, annulée ou remboursée n'est jamais rouverte par une ancienne notification. Un second paiement pour une commande déjà payée, par exemple depuis deux onglets de navigateur, est enregistré sous forme de note de commande, 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 la commande comme payée, car ECPay n'encaisse aucun argent pour eux.
Remboursements
Les remboursements depuis WooCommerce ne sont pas disponibles. Remboursez le paiement dans le back-office ECPay, puis enregistrez manuellement le remboursement dans WooCommerce.
Clé de licence
L'extension fonctionne avec une clé de licence VibeFox provenant de vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > ECPay (綠界). 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 le statut à nouveau, 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 domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez l'emplacement dans votre compte vibefox.net.
Sans clé active, ECPay n'est pas affiché aux clients lors 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 boutique connectés voient toujours la méthode de paiement, marquée (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 des extensions et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés.
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
ECPay n'apparaît pas lors du paiement : vérifiez que la licence est active, que Enable/Disable est activé, que la devise de la boutique est le TWD et que, en mode production, le Merchant ID, la Hash Key et la Hash IV sont renseignés. La page de réglages affiche une erreur dans chacun de ces cas.
Le paiement a été effectué, mais la commande reste En attente de paiement : la notification ECPay n'a pas atteint votre site (site hors ligne, pare-feu, mode maintenance, authentification de base). ECPay réessaie plusieurs fois. Vous pouvez aussi vérifier la transaction dans le back-office ECPay et finaliser la commande manuellement. Activez Enable Logging pour voir les notifications reçues par l'extension.
La notification répond 0|CheckMacValue verification failed : la Hash Key ou la Hash IV ne correspond pas à votre compte ECPay. 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.
Le client voit The order total is too small for ECPay. : le total de la commande est inférieur à 1 TWD après arrondi et ne peut pas être payé avec ECPay.
La commande est En attente avec une note d'écart de montant : le montant signalé par ECPay diffère du total de la commande, par exemple parce que la commande a été modifiée après le début du paiement par le client. Comparez avec le back-office ECPay et finalisez ou remboursez la commande manuellement.
La commande est En attente après un paiement sandbox : le paiement a été effectué en mode test, mais la boutique est maintenant en mode production. Aucun argent réel n'a été encaissé. Vérifiez la commande manuellement.
Le client voit Too many payment attempts for this order : la commande a atteint 30 tentatives de paiement. Demandez au client de passer une nouvelle commande.
Le bloc de licence affiche une erreur : suivez le message du 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 licence est inaccessible, 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 sont toujours supprimés. Les réglages, les données ECPay stockées sur les commandes et les journaux ne sont supprimés que si Delete Data on Uninstall était activé. Sinon, ils restent pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.
ECPay est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à ECPay, ni approuvée par ECPay.