VibeFox Eupago for WooCommerce — Aide

Prérequis

WordPress : 6.0 ou ultérieur.

WooCommerce : 7.0 ou ultérieur, installé et activé.

PHP : 8.0 ou ultérieur.

Devise de la boutique : euro (EUR). Eupago n'encaisse qu'en euros ; pour les autres devises, la méthode de paiement est masquée lors du paiement.

Compte Eupago : il vous faut la clé API de votre canal Eupago et 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, celui de sandbox est sandbox.eupago.pt. Sandbox et production sont des 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier wcp_eupago_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Eupago > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page Plugins.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

5. 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).

6. Choisissez le Payment Method, activez Enable/Disable, passez une commande de test en mode sandbox, puis décochez Sandbox Mode.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Eupago. Lorsque la passerelle est activée, la page vous avertit si la clé API du mode actuel est vide (la passerelle est alors masquée lors du paiement), ou affiche Sandbox mode: no real payments are taken. tant que le mode sandbox est actif. Dans la liste des méthodes de paiement, Eupago est signalé comme nécessitant une action tant que la clé API du mode actuel n'est pas renseignée, et affiche un badge de mode test en mode sandbox.

Général

Enable/Disable : Enable Eupago Gateway active ou désactive la méthode de paiement. Par défaut : off.

Title : le nom de la méthode de paiement que voient les clients lors du paiement. Par défaut : Eupago.

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

Payment Method : l'unique méthode Eupago proposée lors du paiement.

Order Status After Payment : le statut de commande défini lorsque le paiement est confirmé : Processing (par défaut) ou Completed. Le statut est défini immédiatement, avec un seul changement de statut et un seul e-mail.

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 Mode : Enable sandbox/test mode utilise sandbox.eupago.pt et les clés sandbox. Aucun paiement réel n'est encaissé. Par défaut : on. Décochez-le pour encaisser de vrais paiements avec les clés de production.

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.

URL du webhook

Le webhook informe 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 des réglages, la méthode POST et le chiffrement activé. L'URL ressemble à https://your-site/wc-api/eupago_payment_callback/. 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é. L'extension 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 : l'extension n'interroge pas Eupago et le retour du client ne paie pas une commande.

Avancé

Debug Log : Enable logging écrit les appels API et les notifications dans WooCommerce > Status > Logs, source wcp_eupago_gateway. Les clés, e-mails et numéros de téléphone complets ne sont pas journalisés. Les erreurs sont toujours journalisées. Par défaut : off.

Delete Data on Uninstall : Delete all plugin data when uninstalling. Si cette case est cochée, les réglages de la passerelle et les journaux sont supprimés lors de la suppression de l'extension. Les commandes et leurs données de paiement sont conservées. Par défaut : off.

Paiement

Le client choisit la méthode de paiement (par défaut Eupago) et passe la commande. En mode sandbox, la page de paiement affiche SANDBOX / TEST MODE. La suite dépend de Payment Method.

Multibanco : lors du paiement, le client voit You will receive Multibanco payment details after placing the order. L'extension crée une référence Multibanco pour le montant total de la commande. La commande passe en attente, le stock est réduit et le panier est vidé. La page de commande reçue affiche Multibanco Payment Details avec l'entité, la référence et le montant. Les mêmes informations sont ajoutées à l'e-mail de commande du client tant que la commande attend le paiement. Le client paie dans un distributeur automatique de billets ou dans sa banque en ligne.

MB WAY : lors du paiement, le client saisit MB WAY Phone Number, prérempli avec le téléphone 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). L'extension envoie la demande de paiement à l'application MB WAY. La commande passe en attente, le stock est réduit et le panier est vidé. La page de commande reçue demande au client d'ouvrir l'application MB WAY et d'approuver la demande dans les 5 minutes.

Credit Card : lors du paiement, 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 site. La commande reste en attente de paiement et le panier est conservé. Après le paiement, le client revient sur la page de commande reçue, qui affiche Your card payment is being confirmed by Eupago. You will receive an e-mail as soon as it is confirmed. jusqu'à l'arrivée de la notification. Si le paiement par carte échoue ou est abandonné, le client arrive sur la page Pay for order 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 chaque méthode, la commande n'est marquée payée qu'après confirmation d'Eupago par une notification vérifiée. Un client peut payer à nouveau une commande non payée depuis la page Pay for order ; chaque référence de paiement créée pour la commande reste valide pour la vérification.

Si Eupago ne peut pas démarrer le paiement, le client voit un court message, 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. La commande ne change pas, et les détails figurent dans le journal.

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). Les textes destinés aux clients sont traduits en portugais.

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

Commandes

Statuts de commande

Pending payment : un paiement par carte a été démarré et Eupago ne l'a pas encore confirmé.

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

Processing or Completed : le paiement a été confirmé. Le statut suit Order Status After Payment. La note de commande affiche la méthode, l'ID de transaction Eupago et la référence. L'ID de transaction de la commande est l'ID de transaction Eupago.

On hold, manual review : Eupago a signalé un paiement avec un montant ou une devise différent, avec une référence qui n'a pas été créée pour cette commande, ou pour une commande entre-temps annulée ou en échec (par exemple une référence Multibanco payée tardivement). La note l'explique. Vérifiez le paiement et le stock, puis terminez la commande manuellement ou remboursez le client. Les notifications ultérieures pour ce paiement ne terminent pas la commande à votre insu.

Cancelled : Eupago a signalé le paiement comme annulé ou expiré, pour la tentative de paiement en cours d'une commande non payée.

Failed : Eupago a signalé une erreur pour la tentative de paiement en cours d'une commande non payée.

Si Eupago signale un autre paiement pour une commande déjà payée (par exemple si 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 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.

Remboursements : les remboursements depuis WooCommerce ne sont pas pris en charge. Remboursez le client dans le back-office Eupago et enregistrez le remboursement dans WooCommerce avec Refund manually.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > Eupago. 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 à nouveau le statut, 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 seul domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez l'emplacement depuis votre compte vibefox.net.

Sans clé active, Eupago n'est pas affiché aux clients lors du paiement. Si un paiement est tout de même démarré, le client voit This payment method is not available. Please choose another one. Les gestionnaires de la 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 Plugins et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées : les paiements déjà démarré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

Eupago n'apparaît pas lors du paiement : vérifiez que la licence est active, que Enable/Disable est activé, que la clé API du mode actuel est renseignée (Sandbox API Key en mode sandbox, Live API Key en mode production) et que la devise de la boutique est EUR. Avec Multibanco, le montant de la commande doit être compris entre 1 € et 999 999,99 €.

Le paiement a abouti, mais la commande reste Pending payment ou On hold : la notification 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 correspond exactement à celle affichée dans les réglages, 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 WooCommerce > Status > Logs, source wcp_eupago_gateway. 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é du webhook dans l'extension ne correspond pas à celle du webhook, ou le webhook n'est ni chiffré ni signé. Copiez à nouveau la clé et gardez le chiffrement activé.

Le webhook répond Webhook key not configured : aucune des deux clés de webhook n'est renseignée. Eupago renvoie la notification après que vous avez collé la clé.

Le webhook répond Decryption failed : la signature est valide, mais le corps 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 la commande a été passée. Une notification sandbox ne paie jamais une commande de production, et inversement.

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.

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 et réessayez.

La commande est On hold après le paiement : lisez la note de commande. 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 terminez la commande ou remboursez le client.

Le bloc de licence affiche une erreur : suivez le message affiché dans le 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 licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.

Pour les développeurs, la documentation de l'extension répertorie les filtres eupago_p_icon (icône de paiement) et eupago_p_card_language (langue de la page de carte Eupago : PT, EN ou ES).

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 de la passerelle et les journaux ne sont supprimés que si Delete Data on Uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes et leurs références Eupago sont toujours conservées. Les commandes existantes gardent leurs notes de paiement et leurs ID de transaction.

Eupago est une marque commerciale de son propriétaire respectif. Cette extension n'est ni affiliée à Eupago ni approuvée par Eupago.