VibeFox eWAY 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 de la boutique : AUD, NZD, SGD, HKD ou MYR. Pour les autres devises de panier, le moyen de paiement n'est pas affiché à l'étape de paiement. Le paiement est encaissé dans la devise du panier.
Compte eWAY : vous avez besoin d'un compte marchand eWAY avec accès à l'API Rapid, ainsi que de sa clé et de son mot de passe Rapid API, disponibles dans MyeWAY sous Settings, API Key. Pour les tests, vous avez besoin d'un compte sandbox eWAY avec sa propre clé et son propre mot de passe. Les clés sandbox et production sont différentes. Rien n'est à configurer dans eWAY : l'URL de retour est envoyée avec chaque 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 eWAY Payment Gateway dans la liste des modules et cliquez sur Configure.
3. Saisissez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).
4. Saisissez votre clé et votre mot de passe d'API sandbox, laissez Sandbox Mode activé, activez Enable/Disable, cliquez sur Save et passez une commande de test.
5. Saisissez votre clé et votre mot de passe d'API production, désactivez Sandbox Mode et cliquez sur Save.
6. Vous pouvez éventuellement ajouter l'URL cron affichée sur la page Configure aux tâches cron de votre serveur (voir Configuration).
À l'installation, le module crée le statut de commande eWAY 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.
Configuration
Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox eWAY Payment Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, un badge indique le mode : SANDBOX — payments go to the eWAY sandbox, no real money is charged. ou LIVE — real payments are taken with the live API key. La page vous avertit lorsque la clé d'API et le mot de passe du mode en cours sont absents (le moyen de paiement n'est alors pas affiché à l'étape de paiement) et lorsque la devise par défaut de la boutique n'est pas prise en charge par eWAY.
eWAY
Enable/Disable: Enable eWAY Payment Gateway active ou désactive le moyen de paiement. Par défaut : désactivé.
Title: le nom du moyen de paiement que voient les clients à l'étape de paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Credit Card (eWAY). Obligatoire.
Description: le texte affiché sous le moyen de paiement à l'étape de paiement. Par défaut : Pay securely using your credit card via eWAY. You will be redirected to the eWAY secure payment page.
Identifiants d'API
La clé et le mot de passe Rapid API se trouvent dans MyeWAY sous Settings, API Key. eWAY propose des guides pour les clés production et sandbox, liés dans cette section. Les clés sandbox et production sont différentes.
Sandbox Mode: les paiements sont envoyés au sandbox eWAY avec la clé et le mot de passe sandbox. Aucun argent réel n'est débité. Par défaut : activé. Désactivez-le pour encaisser des paiements réels avec la clé production. Tant qu'il est activé, les clients voient Test mode: no real payment is taken. sous le moyen de paiement.
Live API Key: la clé Rapid API de votre compte eWAY production.
Live API Password: le mot de passe Rapid API de votre compte eWAY production.
Sandbox API Key: la clé Rapid API de votre sandbox eWAY (compte partenaire/développeur).
Sandbox API Password: le mot de passe Rapid API de votre compte sandbox eWAY.
Les clés et mots de passe enregistrés ne sont jamais réaffichés. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que si vous voulez la modifier.
Clear saved credentials: cochez une clé ou un mot de passe et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.
Return URL / re-checks: aucun webhook ni URL de retour n'a besoin d'être configuré dans eWAY, car l'URL de retour est envoyée avec chaque paiement. Ce champ affiche une URL cron facultative. Appelez-la depuis une tâche cron du serveur, par exemple toutes les 15 minutes. Si un client paie puis ferme son navigateur avant de revenir à la boutique, le paiement est demandé à eWAY environ une heure plus tard et la commande est créée. Si eWAY est injoignable, la vérification est répétée jusqu'à trois fois. Gardez cette URL secrète : elle contient un jeton, et un appel avec un mauvais jeton reçoit la réponse Forbidden.
Commandes
Order Status on Success: le statut de la commande une fois le paiement confirmé par eWAY.
Un montant ou une devise approuvés qui ne correspondent pas à la commande passent toujours en eWAY payment on hold.
Avancé
Debug log: écrit les appels d'API et les résultats de paiement dans logs/eway_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les données de carte, clés, mots de passe, e-mails des clients et codes d'accès ne sont pas journalisés. Les erreurs sont toujours journalisées. 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 all plugin data on uninstall: lorsque l'option est activée, la désinstallation du module supprime les réglages de la passerelle et le journal. Les données de paiement eWAY des commandes et le statut eWAY payment on hold sont toujours conservés. Par défaut : désactivé.
Paiement
À l'étape de paiement, le client choisit le moyen de paiement (par défaut Credit Card (eWAY)) et confirme. Le module demande à eWAY une page de paiement pour le montant total du panier dans la devise du panier, avec PS- et le numéro du panier comme référence de facture, ainsi que l'adresse de facturation et l'e-mail du client, puis envoie le client sur la eWAY Responsive Shared Page. Là, le client paie par carte. Le paiement est encaissé immédiatement. À ce stade, aucune commande n'existe encore.
Après le paiement, le client revient dans votre boutique. Le module ne fait pas confiance au navigateur : il demande à eWAY, de serveur à serveur, le résultat de la page de paiement créée pour ce panier. La commande n'est marquée comme payée qu'une fois que eWAY l'a confirmé et que le montant et la devise approuvés correspondent au panier. La commande est alors créée et le client voit la page standard de confirmation de commande avec Your payment with eWAY has been received. Pour une commande en attente, la page affiche Your payment was received and is being reviewed by the store. We will contact you if anything is needed.
Si eWAY ne peut pas être interrogé à ce moment-là, une page Payment confirmation affiche We have not received the confirmation of your payment from eWAY yet. If you completed the payment, this order will be updated shortly — please do not pay again. avec un bouton Check again et un bouton Back to checkout. La commande est créée lorsque le client relance la vérification ou lorsque l'URL cron s'exécute.
Si le paiement est refusé, le client revient à l'étape de paiement avec la raison, par exemple Your payment was declined: D4451 Insufficient funds. Please try again or use a different payment method. Si le client clique sur Annuler sur la page eWAY, le module vérifie d'abord auprès d'eWAY qu'aucun paiement n'a été effectué (par exemple dans un autre onglet). Le client voit alors You cancelled the payment on the eWAY page. Your order has not been paid — you can try again. Si le paiement n'a pas été finalisé, le message est The payment was not completed. Please try again. Le panier est conservé dans tous les cas.
Le client peut réessayer. Avant la création d'une nouvelle page de paiement, la page précédente du panier est vérifiée auprès d'eWAY. Si elle est déjà payée, la commande est créée au lieu d'un second paiement. Si eWAY ne peut pas créer la page de paiement, le client reste à l'étape de paiement avec un bref message, par exemple Payment error: Unable to connect to eWAY. Please try again. ou eWAY could not start the payment, accompagné des codes d'erreur eWAY.
eWAY n'envoie aucune notification de serveur à serveur pour la Shared Page : le résultat est obtenu au retour du client et via l'URL cron. Le module ne comporte aucun champ de carte sur votre site, ni cartes enregistrées ni abonnements, ni autorisation seule et capture, et n'évalue pas les scores de fraude Beagle (les transactions bloquées par les règles antifraude d'eWAY sont refusées par eWAY lui-même).
Commandes et remboursements
Statuts de commande
No order yet: le client a été redirigé vers eWAY et n'a pas payé, a annulé, le paiement a été refusé ou le résultat n'a pas encore pu être récupéré. Seul le panier existe.
Payment accepted or Delivered: le paiement a été approuvé. Le statut suit Order Status on Success. Le paiement est enregistré avec l'identifiant de transaction eWAY, et une note indique l'identifiant de transaction, le code d'autorisation, la réponse et le mode (sandbox ou production).
eWAY payment on hold: eWAY a approuvé un montant ou une devise différents de ceux du panier (par exemple Approved for partial amount, ou le panier a été modifié après que le client a ouvert la page de paiement), le paiement a été approuvé après que le client l'a annulé sur la page eWAY, ou il a été approuvé après l'annulation de la commande. Le paiement est enregistré avec le montant encaissé par eWAY, et la note l'explique. Vérifiez la commande, puis traitez-la ou remboursez le paiement.
Refunded: le paiement a été entièrement remboursé via le module.
Si un second paiement est approuvé pour un panier déjà payé, la commande n'est pas modifiée. Une note vous demande de rembourser le doublon dans MyeWAY. Un paiement approuvé pour une autre référence de facture n'est jamais appliqué à la commande.
Bloc de paiement eWAY
La page de commande affiche un bloc eWAY payment avec l'identifiant de transaction, le code d'autorisation, la réponse eWAY, le statut, le mode et la référence de facture, le montant payé et remboursé, un badge Sandbox pour les paiements sandbox, l'historique des remboursements et les eWAY notes de la commande.
Remboursements
Dans le bloc eWAY payment, saisissez le montant (le montant non encore remboursé est pré-rempli), éventuellement un motif, puis cliquez sur Refund via eWAY. Confirmez la question Refund this amount through eWAY? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez disposer du 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 qu'eWAY a encaissés : après une approbation pour un montant partiel, vous pouvez donc rembourser jusqu'à concurrence du montant que le client a réellement payé, et non jusqu'au total de la commande. Le remboursement est envoyé dans l'environnement où le paiement a été effectué (sandbox ou production), la clé et le mot de passe API de cet environnement doivent donc être renseignés. Si eWAY refuse le remboursement, le bloc affiche eWAY refund failed: avec les codes eWAY, et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec l'identifiant de transaction du remboursement eWAY. Un remboursement total passe la commande en Refunded. Un remboursement partiel ne modifie pas le statut. Les remboursements sont disponibles une fois que eWAY a approuvé le paiement.
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 eWAY. Les remboursements effectués dans MyeWAY ne sont pas synchronisés avec PrestaShop. Mettez la commande à jour manuellement si nécessaire.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox eWAY Payment Gateway est le premier bloc de Modules > Module Manager > VibeFox eWAY 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-eway 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 la libération d'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 l'emplacement dans votre compte vibefox.net.
Sans clé active, eWAY n'est pas proposé aux clients à l'étape de paiement. Si un paiement est tout de même lancé, le client voit Cette méthode de paiement n'est pas disponible. Veuillez en choisir une autre. La vitrine 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 moment du paiement. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà commencés sont toujours confirmés, et les remboursements fonctionnent.
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 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
eWAY does not appear at checkout: vérifiez que la licence est active, que Enable/Disable est activé, que la clé et le mot de passe d'API du mode en cours sont renseignés (champs sandbox en mode sandbox, champs production en mode production) et que la devise du panier est AUD, NZD, SGD, HKD ou MYR. La page de configuration affiche un avertissement lorsque les identifiants manquent. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client.
The payment went through, but no order was created: le client n'est pas revenu depuis eWAY, ou eWAY n'a pas pu être interrogé à ce moment-là. eWAY n'envoie aucune notification pour la Shared Page. Configurez l'URL cron de Return URL / re-checks : elle récupère le paiement environ une heure plus tard. Vérifiez la transaction dans MyeWAY et consultez le champ Log sur la page du module.
The customer sees This payment method is temporarily unavailable: la clé ou le mot de passe d'API du mode en cours sont absents, ou eWAY les a refusés. Vérifiez les identifiants du mode en cours.
The customer sees eWAY could not start the payment: eWAY a renvoyé des codes d'erreur, affichés dans le message. Souvent, les coordonnées de facturation sont invalides.
The customer sees We could not match this payment to an order: le lien de retour n'appartient à aucun panier de cette boutique, ou eWAY a approuvé un paiement pour une autre référence de facture. Si le client a été débité, retrouvez le paiement dans MyeWAY.
The customer sees We could not check the status of your previous payment attempt: une autre requête traitait le même panier. Le client peut réessayer dans un instant.
Order is eWAY payment on hold after payment: lisez les eWAY notes du bloc eWAY payment (voir Statuts de commande), puis traitez la commande ou remboursez le paiement.
Refund fails with a message about the sandbox or live mode: la commande a été payée dans cet environnement, et sa clé et son mot de passe d'API ne sont pas renseignés. Saisissez-les et réessayez.
Refund fails with at most … can be refunded: le montant est supérieur à ce qu'eWAY a encaissé, déduction faite des remboursements déjà effectués.
Pour les développeurs : le README du module indique le hook actionWcpEwaySupportedCurrencies, si votre compte eWAY est activé pour d'autres devises.
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox eWAY Payment Gateway et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete all plugin data on uninstall est activé, les réglages de la passerelle 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 données de paiement eWAY des commandes et le statut eWAY payment on hold sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.
eWAY est une marque de son propriétaire respectif. Ce module n'est ni affilié à eWAY ni approuvé par eWAY.