VibeFox Mollie 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 antérieures de PHP.

Devise de la boutique : la devise du panier doit être l'une des devises prises en charge par Mollie : AED, AUD, BGN, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, ILS, ISK, JPY, MXN, MYR, NOK, NZD, PHP, PLN, RON, SEK, SGD, THB, TWD, USD, ZAR. Pour les autres devises, l'option de paiement est masquée dans le tunnel de commande. Les moyens de paiement proposés par Mollie dépendent de la devise et de votre compte.

Accès à Internet pour votre boutique : Mollie envoie des webhooks à votre boutique, le site doit donc être accessible depuis Internet. Sans webhooks, les commandes sont tout de même créées lorsque le client revient de Mollie.

Compte Mollie : vous avez besoin des clés API de Mollie Dashboard > Developers > API keys. Les clés de test commencent par test_, les clés de production par live_. Aucune autre clé ni aucun secret n'est nécessaire. Les moyens de paiement eux-mêmes s'activent dans votre compte Mollie.

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 Mollie Gateway dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans le champ License key du bloc de licence en haut de la page Configure et cliquez sur Activate (voir Clé de licence).

4. Saisissez vos clés API de test et de production (voir Configuration). Aucun webhook n'a besoin d'être configuré dans Mollie.

5. Activez Enable/Disable et cliquez sur Save. Laissez Test Mode activé jusqu'à ce que vous ayez effectué un paiement test, puis désactivez-le.

À l'installation, le module crée deux statuts de commande, Awaiting Mollie payment et Mollie 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 restreindre dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Mollie Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, la page vous avertit lorsque Mollie est activé mais que la clé API du mode actuel est vide, et lorsque Mollie ne prend pas en charge la devise par défaut de la boutique. Dans les deux cas, l'option de paiement est masquée dans le tunnel de commande.

À l'enregistrement, une clé API qui ne commence pas par test_ ou live_ suivi d'au moins 30 lettres et chiffres n'est pas enregistrée : un message d'erreur s'affiche et la clé enregistrée précédemment est conservée.

Tunnel de commande

Enable/Disable : Enable Mollie Gateway active ou désactive l'option de paiement. Par défaut : off.

Title : le titre du moyen de paiement affiché au client dans le tunnel de commande. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Mollie. Obligatoire.

Description : la description du moyen de paiement affichée au client dans le tunnel de commande. Par défaut : Pay securely via Mollie.

Clés API

Retrouvez vos clés API dans le Mollie Dashboard, sous Developers > API keys ; la section renvoie vers cette page. Les clés de test et de production sont distinctes.

Test Mode : utilise la clé API de test pour les nouveaux paiements. Aucun paiement réel n'est traité. Sur la page de paiement test de Mollie, vous pouvez choisir le résultat du paiement. Les clients voient Test mode: no real payment will be made. sous l'option de paiement. Les paiements effectués dans l'autre mode continuent d'utiliser la clé de leur propre mode pour les vérifications de statut et les remboursements. Par défaut : on.

Test API Key : votre clé API de test Mollie (commence par test_).

Live API Key : votre clé API de production Mollie (commence par live_).

Les clés 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 pour la modifier.

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

Webhook : affiche l'URL du webhook. Aucune configuration n'est nécessaire : le module envoie cette URL à Mollie avec chaque paiement. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_mollie_gateway/webhook, éventuellement avec un code de langue. Elle doit être accessible depuis Internet, sinon les commandes ne sont créées que lorsque le client revient de Mollie.

Commandes

Order Status After Payment : le statut de commande défini après un paiement réussi. Le statut est défini en une seule étape.

Processing : la commande passe en Payment accepted (par défaut).

Completed : la commande passe en Delivered.

Les virements bancaires attendent dans Awaiting Mollie payment. Les paiements autorisés et les écarts de montant ou de devise passent en Mollie payment on hold.

Avancé

Logging : écrit les appels API et les webhooks dans logs/molg_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et les avertissements sont toujours journalisés, même si cette option est désactivée. Les clés API et les données clients ne sont jamais journalisées. Par défaut : off.

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, les réglages du module et son journal sont supprimés à la désinstallation du module. Les identifiants de paiement Mollie enregistrés avec les commandes, les historiques de remboursement et les statuts de commande du module sont toujours conservés. Par défaut : off.

Tunnel de commande

À l'étape de paiement, le client choisit l'option de paiement (par défaut Mollie) et confirme. Le module crée un paiement Mollie pour le total du panier dans la devise du panier (JPY et ISK sans décimales), avec la description Order # et le numéro du panier, puis envoie le client sur la page de paiement hébergée de Mollie. Là, le client choisit l'un des moyens de paiement activés dans votre compte Mollie et paie. Aucune commande n'existe encore à ce stade.

Les webhooks Mollie ne comportent aucune signature, seulement l'identifiant du paiement. Le module ne fait donc jamais confiance à un webhook en tant que tel : il n'accepte que les identifiants de paiement qu'il a lui-même créés, lit le paiement dans l'API Mollie avec la clé du mode dans lequel le paiement a été effectué, vérifie que le paiement appartient au panier et compare le montant et la devise payés au total du panier. La commande n'est marquée payée qu'après confirmation de Mollie de cette manière. Le module gère les statuts de paiement Mollie suivants :

paid : le paiement a été effectué. La commande est créée dans le statut Order Status After Payment lorsque le montant et la devise correspondent.

authorized : le paiement a été autorisé mais non capturé. La commande est créée dans Mollie payment on hold avec une note ; capturez-le dans le Mollie Dashboard et la commande est automatiquement marquée payée.

open (bank transfer) : Mollie attend l'argent. La commande est créée dans Awaiting Mollie payment et marquée payée lorsque Mollie reçoit les fonds.

open, pending : le paiement n'est pas encore terminé. Rien ne change.

failed, expired, canceled : la dernière tentative de paiement n'a pas abouti. Sans commande, le client peut simplement payer à nouveau ; une commande en attente de ce paiement passe en Payment error.

chargeback : Mollie signale un montant rétrofacturé. Une note est ajoutée et une commande payée est mise en attente.

Lorsque le client revient, le module vérifie de la même manière le dernier paiement du panier auprès de l'API Mollie. Un paiement effectué mène à la page standard de confirmation de commande avec Your payment with Mollie has been received. Pour un virement bancaire, la page affiche Your order will be processed as soon as Mollie receives your bank transfer. Si la commande est en attente, la page affiche We are confirming your payment with Mollie. The order will be updated automatically — please do not pay again. Si le paiement d'une commande existante a échoué ou si la commande a été annulée, la page affiche Your Mollie payment was not completed. Please contact us about this order.

Si le paiement a été annulé, a échoué, a expiré ou n'a pas été finalisé, le client revient au tunnel de commande avec un message, par exemple You cancelled the Mollie payment. You can try again or choose another payment method. ou The Mollie payment has expired. Please try again or choose another payment method. Le panier est conservé. Si Mollie est injoignable ou n'a pas encore tranché, une page Payment confirmation demande au client de ne pas payer à nouveau et propose un bouton Check again ; le webhook crée la commande dès son arrivée.

Lorsque le client paie à nouveau, le paiement Mollie encore ouvert pour le même montant est réutilisé au lieu d'en créer un second payable. Si le total du panier a changé, l'ancien paiement ouvert est annulé chez Mollie lorsque Mollie le permet. Si l'ancien paiement a été réglé entre-temps, la commande est créée sans nouveau paiement.

Si Mollie ne peut pas démarrer le paiement, le client reste dans le tunnel de commande avec un bref message, par exemple The payment provider could not be reached. Please try again in a moment., This payment method is temporarily unavailable. Please choose another payment method. (clé API incorrecte) ou Mollie cannot accept a payment of this amount or currency. Please choose another payment method. La raison technique est écrite dans le journal.

Le webhook fonctionne lorsque la boutique est en mode maintenance et n'est pas bloqué par la restriction géographique de votre boutique.

Le client choisit le moyen Mollie sur la page Mollie, et non dans le tunnel de commande de votre boutique. Le module ne gère ni abonnements ni paiements récurrents, ni cartes enregistrées ou mandats, ni champs de carte sur votre site, ni boutons express Apple Pay ou PayPal, et n'utilise pas l'Orders API : Mollie ne propose donc pas, pour ces paiements, les moyens qui nécessitent des lignes de commande (par exemple certaines variantes de Klarna, Billie ou in3). Les paiements autorisés se capturent ou s'annulent dans le Mollie Dashboard, et non depuis PrestaShop.

Commandes et remboursements

Statuts de commande

Pas encore de commande : le client a été envoyé chez Mollie et n'a pas payé, ou Mollie n'a pas encore confirmé le paiement. Seul le panier existe.

Payment accepted ou Delivered : le paiement a été confirmé. Le statut suit Order Status After Payment. Le paiement est enregistré avec l'identifiant de paiement Mollie (tr_...) comme identifiant de transaction, et une note indique le paiement Mollie, le moyen de paiement et le mode.

Awaiting Mollie payment : le client a choisi le virement bancaire sur la page Mollie. La commande passe au statut payé lorsque Mollie reçoit l'argent.

Mollie payment on hold : un paiement autorisé attend sa capture, Mollie a signalé une rétrofacturation, le montant ou la devise payés différaient du panier (par exemple, le panier a été modifié après le début du paiement), un paiement test a été effectué alors que la boutique était en mode production (aucun argent n'a été reçu), ou le paiement est arrivé après l'annulation de la commande. La note l'explique. Vérifiez le paiement dans le Mollie Dashboard, puis traitez la commande ou remboursez le paiement.

Payment error : un virement bancaire ou une autorisation d'une commande existante a échoué, expiré ou été annulé. Une commande payée n'est jamais modifiée.

Refunded : le paiement a été entièrement remboursé via le module.

Si un second paiement du même panier est réglé, la commande ne change pas. Une note vous demande de rembourser le paiement en double dans votre Mollie Dashboard.

Bloc Mollie payment

La page de commande affiche un bloc Mollie payment avec l'identifiant de paiement Mollie, le moyen de paiement, le statut du paiement, le montant payé et remboursé, un badge Test mode pour les paiements test, l'historique des remboursements et les Mollie notes de la commande. Les notes ne sont visibles que dans le back office.

Remboursements

Dans le bloc Mollie payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Mollie. Confirmez la question Refund this amount through Mollie? 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 sont effectués dans le montant et la devise que Mollie a encaissés : après un écart de montant, vous pouvez donc rembourser jusqu'au montant réellement payé par le client, et non jusqu'au total de la commande. Le remboursement est envoyé pour le paiement qui a réellement réglé la commande, avec la clé API du mode dans lequel il a été effectué ; cette clé doit donc être renseignée. Si Mollie refuse le remboursement, le bloc affiche le message d'erreur de Mollie et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec l'identifiant du remboursement Mollie. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut. Les remboursements sont disponibles une fois que Mollie a signalé le paiement comme payé.

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 Mollie. Les remboursements créés dans le Mollie Dashboard n'apparaissent pas sur la commande ; une rétrofacturation ajoute une note.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Mollie Gateway est le premier bloc de la page Modules > Module Manager > VibeFox Mollie 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 supprimer la clé de cette boutique. En dessous figurent la ligne Product: presta-payment-mollie 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. Supprimer la clé de la boutique ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, Mollie n'est pas affiché aux clients dans le tunnel 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 vitrine PrestaShop ne sait pas que vous êtes connecté au back office : le moyen de paiement est donc masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester dans le tunnel de commande. Un rappel apparaît dans Modules > Module Manager, sur l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancé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

Mollie n'apparaît pas dans le tunnel de commande : vérifiez que la licence est active, que Enable/Disable est activé et que le mode actuel dispose d'une clé API : Test API Key en mode test, Live API Key en mode production. Vérifiez que la devise du panier est prise en charge par Mollie. La page des réglages affiche un avertissement en cas de clé manquante et de devise de boutique non prise en charge. 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 : le webhook ne peut pas atteindre votre boutique. L'URL affichée sous Webhook doit être accessible depuis Internet (sans authentification de base ni pare-feu qui la bloque). La commande est aussi créée lorsque le client revient dans la boutique après avoir payé, ou lorsqu'il clique sur Check again.

Le webhook répond Unknown payment. : le paiement n'a pas été créé par cette boutique, ou Mollie ne le connaît pas avec la clé API de son mode, par exemple un paiement d'un autre compte Mollie.

Le webhook répond Payment ID mismatch. : le paiement n'appartient pas au panier pour lequel il a été créé. Rien n'est modifié.

Le webhook répond Failed to fetch payment. : l'API Mollie n'a pas pu être jointe, ou la clé API du mode du paiement n'est pas renseignée. Mollie réessaiera le webhook plus tard.

Le webhook répond Temporarily unavailable. : 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, le module est désactivé). Mollie réessaiera le webhook. Activez Logging pour voir la raison.

L'URL du webhook affiche Method not allowed. dans le navigateur : c'est normal. L'URL n'accepte que les requêtes provenant de Mollie.

Une clé API n'est pas enregistrée : la clé doit commencer par test_ ou live_ suivi d'au moins 30 lettres et chiffres. Copiez-la à nouveau depuis le Mollie Dashboard.

Le client voit une erreur lorsqu'il choisit Mollie : consultez le champ Log sur la page du module. Il affiche le code HTTP et le message de Mollie. 401 signifie une clé API incorrecte ; 422 désigne un champ de la requête, par exemple un montant ou une devise que Mollie n'accepte pas.

La commande est en Mollie payment on hold : lisez les notes de la commande (voir Statuts de commande), puis traitez la commande ou remboursez le paiement.

Le remboursement échoue avec un message concernant le mode : le paiement a été effectué en mode test ou production, et la clé API de ce mode n'est pas renseignée. Saisissez-la et réessayez.

Autres devises ou données de paiement : les développeurs peuvent modifier la liste des devises avec le hook actionWcpMollieSupportedCurrencies et la requête de paiement avec le hook actionWcpMolliePaymentData.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Mollie Gateway et choisissez Uninstall. La clé de licence et le statut de 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 identifiants de paiement et les historiques de remboursement Mollie ainsi que les statuts de commande Awaiting Mollie payment et Mollie 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.

Mollie est une marque de son propriétaire respectif. Ce module n'est ni affilié à Mollie ni approuvé par Mollie.