VibeFox Eupago 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 : euro (EUR). Eupago n'encaisse qu'en euros ; pour les paniers dans d'autres devises, la méthode de paiement est donc masquée sur la page de commande.

Compte Eupago : vous avez besoin de la clé API de votre canal Eupago et de la clé d'un Webhook 2.0 que vous créez dans le back-office Eupago (voir Configuration). Le back-office de production est clientes.eupago.pt, le back-office sandbox est sandbox.eupago.pt. Sandbox et production sont deux comptes distincts avec des clés distinctes.

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 Eupago 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 la clé API de votre canal Eupago, créez un Webhook 2.0 dans le back-office Eupago et collez sa clé (voir Configuration).

5. Choisissez la Payment Method, activez Enable/Disable et cliquez sur Save. Passez une commande de test en mode sandbox, puis désactivez Sandbox Mode.

À l'installation, le module crée deux statuts de commande : Awaiting Eupago payment et Eupago payment on hold. PrestaShop active un nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les restreindre dans Payment > Preferences ; l'euro doit rester autorisé pour le module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Eupago Gateway > Configure. Chaque section possède son propre bouton Save, qui enregistre toute la page. Lorsque la méthode de paiement est activée, la page vous avertit au-dessus des champs si la clé API du mode actuel est vide (la méthode de paiement est alors masquée sur la page de commande), ou affiche Sandbox mode: no real payments are taken. tant que le mode sandbox est activé.

Eupago

Enable/Disable : Enable Eupago Gateway 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 sur la page de commande. C'est aussi le nom de la méthode de paiement enregistré dans la commande. Par défaut : Eupago. Obligatoire : un titre vide affiche Enter a title for the payment method.

Description : le texte affiché sous la méthode de paiement sur la page de commande. Par défaut : Pay securely via Eupago.

Payment Method : l'unique méthode Eupago proposée sur la page de commande.

Order Status After Payment : le statut de commande attribué lorsque le paiement est confirmé.

Compte Eupago

Récupérez la clé API de votre canal et la clé du Webhook 2.0 dans le back-office Eupago : clientes.eupago.pt (production) ou sandbox.eupago.pt (sandbox). Sandbox et production sont deux comptes distincts avec des clés distinctes.

Sandbox Mode : utilise sandbox.eupago.pt et les clés sandbox. Aucun paiement réel n'est encaissé. Par défaut : activé. Désactivez-le pour encaisser de vrais paiements avec les clés de production. Tant qu'il est activé, les clients voient SANDBOX / TEST MODE sous la méthode de paiement.

Live API Key : la clé API de votre canal Eupago de production (clientes.eupago.pt).

Live Webhook Key : la clé de chiffrement de votre Webhook 2.0 de production. Obligatoire : les notifications sans signature valide sont rejetées.

Sandbox API Key : la clé API de votre canal sandbox (sandbox.eupago.pt).

Sandbox Webhook Key : la clé de chiffrement de votre Webhook 2.0 sandbox.

Les clés enregistrées ne sont plus jamais affichées. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement si vous voulez la modifier.

Clear saved keys : cochez une clé et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

URL du webhook

Le webhook indique à votre boutique qu'un paiement a été effectué. Dans le back-office Eupago, créez un Webhook 2.0 avec l'URL affichée dans cette section, la méthode POST et le chiffrement activé. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_eupago_gateway/webhook, éventuellement avec un code de langue comme /pt/. Copiez l'URL exactement telle que les réglages l'affichent. Créez un webhook dans le back-office sandbox et un autre dans le back-office de production.

Copiez la clé de chaque webhook dans Sandbox Webhook Key ou Live Webhook Key. Les webhooks sans signature valide sont rejetés. Un webhook non chiffré n'est accepté que si Eupago le signe ; gardez donc le chiffrement activé. Une notification doit être signée avec la clé du mode dans lequel le paiement a été lancé : une notification sandbox ne paie donc jamais un paiement de production. Le module réagit aux statuts de notification suivants :

Les autres statuts ne nécessitent aucune action. Le callback GET hérité d'Eupago vers la même URL est également accepté ; il est authentifié par la clé API et signale toujours un paiement. Sans notifications, les commandes ne sont jamais marquées payées : le module n'interroge pas Eupago, et le retour du client ne paie aucune commande. Le webhook fonctionne lorsque la boutique est en mode maintenance et n'est pas bloqué par la restriction géographique de votre boutique.

Avancé

Debug Log : écrit les appels API et les notifications dans logs/eupago_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les clés, les e-mails et les numéros de téléphone complets 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 Data on Uninstall : lorsqu'il est activé, la désinstallation du module supprime les réglages de la passerelle, les enregistrements de paiements Eupago de ce module et le journal. Les commandes et leurs données de paiement sont conservées. Par défaut : désactivé.

Paiement

Le client choisit la méthode de paiement (par défaut Eupago) à l'étape de paiement et passe commande. La suite dépend de la Payment Method.

Multibanco : sur la page de commande, le client voit You will receive Multibanco payment details after placing the order. Le module crée une référence Multibanco pour le total du panier. La commande est immédiatement créée en Awaiting Eupago payment, comme toute commande PrestaShop, et le panier est vidé. La page de confirmation de commande affiche Multibanco Payment Details avec l'entité, la référence et le montant. Les mêmes informations sont ajoutées à la ligne de paiement de l'e-mail de confirmation de commande. Le client paie dans un distributeur automatique de billets ou dans sa banque en ligne.

MB WAY : sur la page de commande, le client saisit le MB WAY Phone Number, pré-rempli avec le téléphone de l'adresse de facturation. Les numéros portugais peuvent être saisis sans +351. Un numéro erroné affiche Please enter a valid MB WAY phone number (e.g. 912 345 678 or +351 912 345 678). Le module envoie la demande de paiement à l'application MB WAY et crée la commande en Awaiting Eupago payment. La page de confirmation de commande invite le client à ouvrir l'application MB WAY sur le numéro masqué et à approuver la demande dans les 5 minutes.

Credit Card : sur la page de commande, le client voit You will be redirected to a secure payment page to enter your card details. Le client est envoyé sur la page de carte d'Eupago, en portugais, en espagnol ou en anglais selon la langue du panier. Aucune commande n'existe encore, et le panier est conservé. La commande n'est créée que lorsque Eupago confirme le paiement. Si la notification est arrivée au retour du client, celui-ci voit la page standard de confirmation de commande. Sinon, une page Payment confirmation affiche Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. avec un bouton Check again. Si le paiement par carte échoue ou est abandonné, le client revient sur la page de commande avec The card payment was not completed. You can try again or choose another payment method. ou The card payment was cancelled. You can try again or choose another payment method.

Pour toutes les méthodes, la commande n'est marquée payée qu'après la confirmation d'Eupago par une notification vérifiée. Les détails de paiement ne sont affichés que tant que la commande est en Awaiting Eupago payment. Si Eupago signale ensuite que le paiement a été annulé, a expiré ou a échoué, et que la commande n'était pas payée, la page de confirmation de commande affiche Your Eupago payment was not completed. Please contact us about this order.

Si Eupago ne peut pas démarrer le paiement, le client reste sur la page de commande avec un message bref, par exemple The payment could not be started because Eupago is temporarily unavailable. Please try again in a few minutes or choose another payment method. Aucune commande n'est créée, et les détails figurent dans le journal. Un panier dans une autre devise affiche Eupago only supports payments in EUR.

Le module propose une seule méthode Eupago par installation. Il ne prend pas en charge les remboursements depuis PrestaShop, ni les cartes enregistrées, les abonnements ou la pré-autorisation, ni PayShop, Cofidis Pay, Bizum ou les autres méthodes Eupago, ni les rappels par SMS, ni la date d'expiration Multibanco, ni l'interrogation du statut.

Commandes

Statuts de commande

No order yet : un paiement par carte a été lancé et Eupago ne l'a pas encore confirmé. Seul le panier existe.

Awaiting Eupago payment : une référence Multibanco ou une demande MB WAY a été créée. La note affiche l'entité et la référence, ou le numéro de téléphone masqué.

Payment accepted or Delivered : le paiement a été confirmé. Le statut suit Order Status After Payment. Le paiement est enregistré avec l'ID de transaction Eupago comme ID de transaction, et une note indique la méthode, l'ID de transaction et la référence.

Eupago payment on hold : Eupago a signalé un paiement d'un montant ou d'une devise différents, avec une référence qui n'a pas été créée pour ce panier, ou pour une commande qui avait entre-temps été annulée ou avait échoué (par exemple une référence Multibanco payée en retard). La note l'explique. Vérifiez le paiement et le stock, puis finalisez la commande manuellement ou remboursez le client. Les notifications ultérieures pour ce paiement ne finalisent pas la commande à votre insu.

Canceled : Eupago a signalé le paiement comme annulé ou expiré, pour la tentative de paiement en cours d'une commande en attente.

Payment error : Eupago a signalé une erreur pour la tentative de paiement en cours d'une commande en attente.

Si Eupago signale un autre paiement pour une commande déjà payée (par exemple, une ancienne référence Multibanco a également été payée), la commande n'est pas modifiée. Une note vous demande de vérifier s'il s'agit d'un paiement en double et de le rembourser dans le back-office Eupago. Une notification de paiement ne rouvre jamais une commande payée puis annulée ou remboursée.

Bloc de paiement Eupago

La page de commande affiche un bloc Eupago payment avec chaque tentative de paiement du panier : date, méthode, un badge Sandbox pour les paiements sandbox, montant, l'entité et la référence Multibanco ou le téléphone masqué MB WAY, l'ID de transaction Eupago et le statut. Tant que la commande est en Eupago payment on hold, le bloc affiche un avertissement Manual review. Plus bas, Eupago notes liste les notes du module sur la commande, de la plus récente à la plus ancienne.

Remboursements

Les remboursements depuis PrestaShop ne sont pas pris en charge. Remboursez le client dans le back-office Eupago et 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 Eupago.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Eupago Gateway est le premier bloc de Modules > Module Manager > VibeFox Eupago 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) 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-eupago 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, Eupago n'est pas proposé aux clients sur la page 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, si bien que la méthode de paiement est aussi masquée pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester sur la page 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 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

Eupago n'apparaît pas sur la page de commande : vérifiez que la licence est active, que Enable/Disable est activé et que la clé API du mode actuel est renseignée (Sandbox API Key en mode sandbox, Live API Key en mode production). La devise du panier doit être EUR, et dans Payment > Preferences, le module doit être autorisé pour l'euro, le pays du client et le groupe du client. Avec Multibanco, le total de la commande doit être compris entre 1 € et 999 999,99 €.

Le paiement a été effectué, mais la commande reste en Awaiting Eupago payment ou aucune commande n'a été créée : la notification d'Eupago n'arrive pas ou est rejetée. Dans le back-office Eupago du mode utilisé, vérifiez que le Webhook 2.0 existe, que son URL est exactement celle affichée dans Webhook URL, que la méthode est POST et que le chiffrement est activé. Vérifiez que sa clé se trouve dans le champ correspondant (Sandbox Webhook Key ou Live Webhook Key). Activez Debug Log et consultez le champ Log de la page du module. Si une notification n'arrive jamais, vérifiez le paiement dans le back-office Eupago.

Le webhook répond Invalid signature ou Missing signature : la clé de webhook du module ne correspond pas à celle du webhook, ou le webhook n'est ni chiffré ni signé. Recopiez la clé et gardez le chiffrement activé.

Le webhook répond Webhook key not configured : aucune clé de webhook n'est définie. Eupago renvoie la notification une fois que vous avez collé la clé.

Le webhook répond Decryption failed : la signature est valide, mais le contenu n'a pas pu être déchiffré. Vérifiez les réglages du Webhook 2.0 dans le back-office Eupago.

Le webhook répond Environment mismatch : la notification est signée avec la clé de l'autre mode que celui dans lequel le paiement a été lancé. Une notification sandbox ne paie jamais un paiement de production, et inversement. Vérifiez que les clés sandbox et production ne sont pas inversées.

Le webhook répond Order not found : la notification concerne un panier sans paiement Eupago de cette boutique, par exemple un paiement effectué depuis une autre boutique avec le même canal Eupago.

Le webhook répond Busy or Retry : le panier était en cours de traitement par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple, parce que le module est désactivé). Eupago renvoie la notification. La raison figure dans le journal.

Le callback hérité répond Invalid API key : la clé API envoyée par Eupago ne correspond ni à Live API Key ni à Sandbox API Key. La même réponse s'affiche si vous ouvrez l'URL du webhook dans un navigateur ; c'est normal.

Le client voit The MB WAY payment could not be started : vérifiez que le numéro de téléphone est associé à MB WAY, puis réessayez.

La commande est en Eupago payment on hold après le paiement : lisez les Eupago notes dans le bloc Eupago payment. Le montant ou la devise était différent, la référence était inconnue, ou le paiement est arrivé après l'annulation de la commande. Vérifiez le paiement dans le back-office Eupago, puis finalisez la commande ou remboursez le client.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Eupago Gateway 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 de la passerelle, les enregistrements de paiements Eupago de ce module et le journal sont supprimés. S'il est désactivé, tous les réglages et enregistrements sont conservés pour une réinstallation ultérieure. Les statuts de commande Awaiting Eupago payment et Eupago payment on hold sont toujours conservés. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

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