VibeFox ePayco for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les versions de PHP antérieures.

Devise : peso colombien (COP) ou dollar américain (USD). Pour les paniers dans d'autres devises, le moyen de paiement est masqué lors du paiement.

Compte ePayco : vous avez besoin des quatre clés de votre compte ePayco : P_CUST_ID_CLIENTE, P_KEY, PUBLIC_KEY et PRIVATE_KEY. Elles se trouvent dans le tableau de bord ePayco, sous Integrations, API keys. Les mêmes clés fonctionnent en mode test et en mode production. Les moyens de paiement que le client peut utiliser (cartes, PSE, réseaux de paiement en espèces, portefeuilles) sont ceux activés sur votre compte ePayco.

Site public : l'URL de confirmation de votre boutique doit être accessible depuis Internet, sans être bloquée par un pare-feu ou une authentification de base.

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échargement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox ePayco Payment 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 les quatre clés ePayco et choisissez le type de paiement (voir Configuration).

5. Activez Enable/Disable et cliquez sur Save. Testez un paiement avec Test Mode activé et les cartes de test ePayco, puis désactivez Test Mode.

À l'installation, le module crée deux statuts de commande, Awaiting ePayco payment et ePayco payment on hold. PrestaShop active par défaut un nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez le restreindre dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox ePayco Payment > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, la page vous avertit lorsque les quatre clés ne sont pas toutes saisies (le moyen de paiement est alors masqué lors du paiement) et lorsque la devise par défaut de votre boutique n'est ni COP ni USD, et affiche Test mode is on: customers pay with ePayco test cards and no real money is charged. tant que le mode test est activé.

ePayco

Enable/Disable: Enable ePayco Payment active ou désactive le moyen de paiement. Par défaut : désactivé.

Title: le nom du moyen de paiement que le client voit lors du paiement. C'est aussi le nom enregistré dans la commande. Par défaut : ePayco.

Description: le texte affiché sous le moyen de paiement lors du paiement. Par défaut : Pay securely with ePayco.

Clés du compte ePayco

Retrouvez les quatre clés dans le tableau de bord ePayco, sous Integrations, API keys. P_CUST_ID_CLIENTE et P_KEY vérifient les confirmations de paiement ; PUBLIC_KEY et PRIVATE_KEY créent les sessions de paiement. Les mêmes clés fonctionnent en mode test et en mode production.

Customer ID (P_CUST_ID_CLIENTE): votre identifiant client ePayco (numérique).

Secret Key (P_KEY): sert à vérifier la signature des confirmations de paiement ePayco. Gardez-la secrète.

Public Key (PUBLIC_KEY): votre clé publique d'API ePayco.

Private Key (PRIVATE_KEY): votre clé privée d'API ePayco. Gardez-la secrète.

Les clés secrètes enregistrées ne sont jamais réaffichées. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que si vous voulez la modifier.

Effacer les clés secrètes enregistrées : cochez Secret Key (P_KEY) ou Private Key (PRIVATE_KEY) et cliquez sur Save pour supprimer la clé. Un champ vide conserve la valeur enregistrée.

Test Mode: les sessions de paiement sont créées comme transactions de test. Les clients paient avec les cartes de test ePayco et aucun argent réel n'est débité. Les transactions de test ne règlent jamais les commandes créées en mode production. Par défaut : désactivé. Tant qu'il est activé, les clients voient TEST MODE — use ePayco test cards, no real money is charged. sous le moyen de paiement et sur la page de paiement.

Paiement

Checkout Type: la manière dont s'ouvre la page de paiement ePayco.

URL de confirmation

L'URL de confirmation indique à votre boutique le résultat d'un paiement. Elle est transmise automatiquement à ePayco avec chaque paiement : il n'y a donc rien à configurer dans le tableau de bord ePayco. La section affiche l'URL. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_epayco_payment/confirmation, éventuellement avec un code de langue comme /en/. Elle doit être accessible depuis Internet, sans être bloquée par un pare-feu ou une authentification de base. Elle fonctionne pendant la maintenance de la boutique et n'est pas bloquée par la restriction géographique de votre boutique.

Chaque confirmation doit porter une signature valide, réalisée avec votre P_CUST_ID_CLIENTE et votre P_KEY. Les confirmations sans signature valide sont rejetées et ne modifient rien. Sans la confirmation, une commande n'est créée que lorsque le client revient sur la boutique après avoir payé.

Avancé

Logging: écrit les erreurs d'API et les confirmations de paiement dans logs/epc_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les clés et les données clients ne sont pas journalisées. Par défaut : désactivé. Les erreurs sont toujours journalisées, même lorsque l'option est désactivée.

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 ses réglages et le journal. Les données ePayco enregistrées pour les commandes et les statuts de commande du module sont toujours conservées, afin que les commandes existantes continuent de fonctionner. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut ePayco) et confirme. Le module crée une session de paiement ePayco pour le total du panier dans la devise du panier, avec les taxes, le numéro de panier, ainsi que le nom de facturation, l'adresse, l'e-mail et le téléphone. Le paiement apparaît chez ePayco sous Cart # suivi du numéro de panier. La langue de la page de paiement est l'espagnol ou l'anglais, selon la langue de la boutique. Aucune commande n'existe encore à ce stade.

Le client voit ensuite la page ePayco payment avec Thank you for your order. The secure ePayco checkout opens automatically; if it does not, click the button below. La page de paiement ePayco s'ouvre en fenêtre contextuelle ou par redirection, selon Checkout Type. La page comporte aussi le bouton Pay with ePayco et le lien Choose another payment method. Chaque clic sur le bouton de paiement crée une nouvelle session ePayco.

Sur la page de paiement ePayco, le client règle avec l'un des moyens activés sur votre compte ePayco. ePayco envoie ensuite la confirmation à votre boutique et renvoie le client. La commande n'est marquée payée qu'après la confirmation d'ePayco : par la confirmation signée, ou par une requête serveur auprès d'ePayco lorsque le client revient. Le simple retour du client ne règle jamais une commande. La commande est alors créée et le client voit la page standard de confirmation de commande.

Pour un paiement en attente (par exemple PSE ou espèces), la commande est créée dans Awaiting ePayco payment et la page de confirmation affiche Your ePayco payment is being confirmed. We will e-mail you as soon as it is approved. Si le paiement en attente est refusé ou expire plus tard, la page affiche Your ePayco payment was not completed. Please contact us about this order. Si ePayco n'a pas encore confirmé le paiement lorsque le client revient, une page Payment confirmation affiche We are waiting for ePayco to confirm your payment. This page does not need to stay open. et un bouton Check again.

Si le paiement a été refusé, le client revient à la page de paiement avec Your ePayco payment was declined or could not be completed. You can try again or choose another payment method. Si le client revient sans avoir payé, le message est The ePayco payment was not completed. If you already paid, the order will be updated as soon as ePayco confirms it; otherwise you can try again. Le panier est conservé et aucune commande n'est créée.

Si ePayco ne peut pas démarrer le paiement, le client reste sur la page de paiement avec un message bref, par exemple We could not connect to ePayco. Please try again in a moment or choose another payment method. La raison technique est inscrite dans le journal.

Le module ne gère que les paiements uniques. Il ne propose ni remboursements depuis la boutique, ni cartes enregistrées, abonnements ou paiements fractionnés, et il n'interroge pas ePayco périodiquement sur les transactions en attente : les commandes sont mises à jour par la confirmation d'ePayco et par le retour du client.

Commandes

Statuts de commande

No order yet: le client a été envoyé vers ePayco et n'a pas payé, ePayco n'a pas encore confirmé le paiement, ou le paiement a été refusé. Seul le panier existe.

Payment accepted: ePayco a approuvé le paiement. Le paiement est enregistré avec la référence ePayco (ref_payco) comme ID de transaction, et une note indique la référence, l'état, le montant, le moyen de paiement et le code d'approbation.

Awaiting ePayco payment: ePayco a signalé le paiement comme en attente ou retenu, par exemple un virement PSE ou un paiement en espèces. La commande change automatiquement lorsqu'ePayco approuve ou rejette le paiement.

ePayco payment on hold: ePayco a approuvé un paiement dont le montant ou la devise diffère de la commande (par exemple, le panier a été modifié après le début du paiement), ou a approuvé un paiement après l'annulation de la commande. Le montant effectivement payé est enregistré sur la commande lorsque la devise correspond. Ne pas expédier avant d'avoir vérifié la transaction dans le tableau de bord ePayco.

Payment error: un paiement en attente a été refusé, a échoué, a expiré ou a été annulé. La note indique le motif donné par ePayco. Un nouveau paiement approuvé pour le panier règle toujours la commande. Un échec tardif ne modifie jamais une commande payée.

Refunded: ePayco a annulé le paiement de cette commande.

Si ePayco signale un autre paiement approuvé pour une commande déjà payée, le statut ne change pas. Une note vous invite à vérifier s'il s'agit d'un double débit et à le rembourser dans ePayco si besoin. Une transaction de test pour une commande passée en mode production, ainsi qu'une transaction déjà rattachée à une autre commande, sont ignorées avec une note.

Bloc de paiement ePayco

La page de commande affiche un bloc ePayco payment avec la référence ePayco (ref_payco), l'ID de transaction, l'état, le moyen de paiement, le code d'approbation, la date de la transaction, un badge Test mode pour les paiements de test et les ePayco notes de la commande. Pour une commande en ePayco payment on hold, le bloc affiche un avertissement invitant à vérifier la transaction avant l'expédition.

Remboursements

Les remboursements depuis la boutique ne sont pas pris en charge. Remboursez le paiement dans le tableau de bord ePayco, puis mettez à jour la commande dans PrestaShop manuellement si nécessaire. Une annulation de la transaction de paiement signalée par ePayco place la commande en Refunded.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox ePayco Payment est le premier bloc de Modules > Module Manager > VibeFox ePayco Payment > 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) et 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-epayco 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 l'emplacement dans votre compte vibefox.net.

Sans clé active, ePayco n'est pas proposé 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. La boutique PrestaShop ne sait pas que vous êtes connecté au back office, si bien que le moyen de paiement est aussi masqué pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester lors 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.

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 que vous travaillez dans le back office : une fois par jour pendant les 14 premiers jours suivant 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 la licence.

Dépannage

ePayco n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé, que les quatre clés sont saisies et que la devise du panier est COP ou USD. La page des réglages affiche un avertissement lorsque des clés 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.

Le paiement a abouti, mais aucune commande n'a été créée : la confirmation d'ePayco n'atteint pas votre boutique. Vérifiez que l'URL de confirmation affichée dans les réglages est accessible depuis Internet et n'est bloquée ni par un pare-feu, ni par un module de sécurité, ni par une authentification de base. Consultez le champ Log de la page du module ; activez Logging pour voir chaque confirmation. La commande est aussi créée lorsque le client revient sur la boutique après avoir payé.

La confirmation répond «Invalid signature» : Customer ID (P_CUST_ID_CLIENTE) ou Secret Key (P_KEY) ne correspond pas au compte ePayco qui a encaissé le paiement. Recopiez les deux depuis le tableau de bord ePayco.

La confirmation répond «Gateway not configured» : P_CUST_ID_CLIENTE ou P_KEY est vide. Saisissez-les dans les réglages.

La confirmation répond «Order not found» : la confirmation concerne un panier sans paiement ePayco de cette boutique.

La confirmation répond «Busy, retry later» : la commande était en cours de mise à jour par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple, le module est désactivé). ePayco réessaie la confirmation. La raison figure dans le journal.

Le client voit «We could not connect to ePayco» : ePayco a refusé PUBLIC_KEY et PRIVATE_KEY. Le journal affiche la réponse d'ePayco. Recopiez les deux clés.

Le client voit «ePayco could not start the payment» : ePayco n'a pas créé la session de paiement. Consultez le journal pour l'erreur d'ePayco.

La page de paiement ePayco ne s'ouvre pas : le client voit The ePayco checkout could not be loaded. Please reload the page or choose another payment method. Le script de la page de paiement ePayco n'a pas pu être chargé. Le client peut recharger la page ou utiliser Choose another payment method.

Un paiement de test n'a pas réglé la commande : les transactions de test ne règlent jamais les commandes passées en mode production. Passez la commande de test lorsque Test Mode est activé.

La commande est en ePayco payment on hold : lisez les notes du bloc ePayco payment (voir Statuts de commande) et vérifiez la transaction dans le tableau de bord ePayco avant l'expédition.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox ePayco Payment et choisissez Uninstall. La clé de licence et le statut de la licence de ce module 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 données ePayco enregistrées pour les commandes et les statuts de commande Awaiting ePayco payment et ePayco payment on hold sont toujours conservées. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

ePayco est une marque déposée de son titulaire respectif. Ce module n'est ni affilié à ePayco ni approuvé par ePayco.