VibeFox Montonio 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 : la devise du panier doit être EUR ou PLN. Pour toute autre devise, le moyen de paiement est masqué à l'étape de paiement.

Compte Montonio : vous avez besoin de la clé d'accès et de la clé secrète de votre boutique, fournies par le Montonio Partner System. Les clés sandbox et production sont différentes : il vous faut donc une paire pour chaque environnement utilisé. Aucune autre configuration n'est nécessaire dans Montonio : l'adresse de notification est envoyée avec chaque paiement.

Site public : votre boutique doit être accessible depuis Internet pour recevoir les notifications de Montonio. Sinon, les commandes sont tout de même créées lorsque le client revient sur la boutique.

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 Montonio Payment 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, puis cliquez sur Activate (voir Clé de licence).

4. Dans le Montonio Partner System, ouvrez Stores > your store > API keys et copiez la clé d'accès et la clé secrète sandbox. Collez-les dans les réglages et laissez Sandbox mode activé.

5. Activez Enable/Disable, cliquez sur Save et testez un paiement dans le sandbox. Saisissez ensuite les clés de production et désactivez Sandbox mode.

À l'installation, le module crée le statut de commande Montonio 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 Montonio Payment > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, la page vous avertit lorsque les clés de l'environnement actuel sont absentes (le moyen de paiement est alors masqué à l'étape de paiement), lorsque la devise de la boutique n'est pas EUR ou PLN, et affiche Sandbox mode is on: payments are simulated and no real money is charged. tant que le sandbox est activé. Title ne peut pas être vide.

Montonio

Enable/Disable : Enable Montonio bank payments active ou désactive le moyen de paiement. Par défaut : désactivé.

Title : le nom du moyen de paiement que les clients voient à l'étape de paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Bank payment (Montonio). Obligatoire.

Description : le texte affiché sous le moyen de paiement à l'étape de paiement. Par défaut : Pay directly from your bank account. You will be redirected to Montonio to choose your bank.

Clés API

Obtenez les clés dans le Montonio Partner System, sous Stores > your store > API keys. Les clés sandbox et production sont différentes. Le sandbox n'utilise que les clés sandbox, et le mode production n'utilise que les clés de production.

Sandbox mode : utilise le sandbox Montonio (paiements de test, aucun argent réel). Il change à la fois l'adresse de l'API Montonio et la paire de clés. Par défaut : activé. Ne le désactivez qu'après avoir saisi les clés de production. Les paiements effectués dans l'autre environnement continuent d'utiliser les clés de leur propre environnement pour les confirmations et les remboursements.

Sandbox access key : la clé d'accès (UUID) de votre boutique dans le sandbox Montonio.

Sandbox secret key : la clé secrète de votre boutique dans le sandbox Montonio.

Live access key : la clé d'accès (UUID) de votre boutique dans l'environnement de production Montonio.

Live secret key : la clé secrète de votre boutique dans l'environnement de production Montonio.

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. Saisissez une nouvelle valeur uniquement pour la modifier.

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

Notification URL : l'adresse à laquelle Montonio envoie les notifications de paiement. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_montonio_payment/webhook. Vous n'avez rien à saisir : le module l'envoie à Montonio avec chaque paiement.

Avancé

Debug log : écrit les événements de paiement dans logs/wc_mnt_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements sont toujours journalisés, même lorsque cette option est désactivée. Les clés, jetons et données client ne sont jamais journalisés. 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 : lorsqu'elle est activée, la désinstallation du module supprime ses réglages et son journal. La désactivation du module ne supprime jamais rien. Les données de commande (UUID Montonio, notes) sont toujours conservées. Par défaut : désactivé.

Notifications de paiement

Montonio informe votre boutique de chaque paiement au moyen d'un jeton signé. Le jeton arrive de deux façons : par une notification serveur à serveur envoyée à l'URL de notification, et avec le client lorsqu'il revient sur la boutique. Les deux sont vérifiés : la signature avec la clé secrète de l'environnement dans lequel le paiement a été créé, la date d'expiration, votre clé d'accès, et le fait que le paiement a bien été créé par votre boutique pour ce panier. Un jeton signé avec la clé de l'autre environnement est rejeté. Chaque statut n'est appliqué qu'une seule fois : les notifications répétées n'ajoutent donc ni notes, ni e-mails, ni modifications de stock. L'URL de notification fonctionne pendant que la boutique est en mode maintenance et n'est pas bloquée par la restriction par pays de votre boutique.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut, Bank payment (Montonio)) et confirme. Le module crée un paiement Montonio pour le total du panier dans la devise du panier et envoie le client sur la page de paiement Montonio. Là, le client choisit une banque et paie. Les banques du pays de facturation du client sont affichées en premier (la Pologne pour les paniers en PLN). Le paiement apparaît sous le nom Order suivi du numéro de panier. La page Montonio s'ouvre dans la langue de la boutique lorsqu'il s'agit de l'allemand, de l'anglais, de l'estonien, du finnois, du lituanien, du letton, du polonais ou du russe ; sinon, elle s'ouvre en anglais. En mode sandbox, la page de paiement affiche SANDBOX MODE — test payment, no real money is charged. sous la description. Aucune commande n'existe encore à ce stade.

La commande n'est marquée comme payée qu'une fois que Montonio l'a confirmée : par la notification ou au retour du client. La commande est alors créée et le client voit la page standard de confirmation de commande avec Your Montonio bank payment has been received. Si la banque n'a pas encore confirmé le paiement, ou si la commande est en attente, la page affiche We are confirming your payment with Montonio. The order will be updated automatically — please do not pay again. Si la banque rejette plus tard un paiement autorisé, la page affiche Your Montonio payment was not completed. Please contact us about this order.

Si Montonio signale que le paiement est encore en attente lorsque le client revient, une page Payment confirmation affiche le même texte, avec un bouton Check again. Ce bouton demande à Montonio le statut actuel du paiement. La notification crée la commande dès son arrivée.

Si le paiement a été annulé ou rejeté, le client revient à la page de paiement avec l'un de ces messages : The payment was cancelled or rejected by the bank. You can try again or choose another payment method., The payment was not completed. You can try again or choose another payment method. ou Montonio could not complete the payment. Please try again or choose another payment method. Le panier est conservé. Avant de créer un nouveau paiement, le module interroge Montonio sur le précédent. S'il est déjà payé, la commande est créée et aucun second paiement n'est effectué.

Si Montonio ne peut pas démarrer le paiement, le client reste à l'étape de paiement avec un court message, par exemple Montonio is temporarily unavailable. Please try again in a few minutes or choose another payment method. La raison technique est écrite dans le journal.

Le module ne prend en charge que les paiements bancaires (initiation de paiement). Il ne gère ni paiements par carte, ni BLIK, ni Apple Pay ou Google Pay, ni Pay Later ou financement, ni expédition Montonio, ni abonnements, ni moyens de paiement enregistrés, ni choix de la banque sur votre propre site.

Commandes et remboursements

Statuts de commande

No order yet: le client a été envoyé vers Montonio et n'a pas payé, ou Montonio signale le paiement comme en attente. Seul le panier existe.

Payment accepted: Montonio a confirmé le paiement (PAID) avec le montant et la devise exacts du panier. Le paiement est enregistré avec l'UUID de commande Montonio comme identifiant de transaction, et une note indique la banque, l'UUID, le montant et l'environnement.

Montonio payment on hold: la banque n'a pas encore confirmé le paiement (AUTHORIZED) ; la commande passe à Payment accepted lorsque Montonio signale PAID. Une commande est aussi mise en attente lorsque Montonio a signalé un montant ou une devise différents du total du panier, lorsqu'un paiement sandbox est arrivé alors que la boutique est en mode production (aucun paiement n'est enregistré, car aucun argent n'a été reçu), ou lorsque le paiement est arrivé après l'annulation de la commande. La note l'explique. Vérifiez le paiement dans le Montonio Partner System, puis traitez la commande ou remboursez le paiement.

Payment error: la banque a rejeté un paiement autorisé, ou le client ne l'a pas finalisé. Seul le dernier paiement du panier peut modifier la commande.

Refunded: le paiement a été intégralement remboursé via le module.

Les commandes payées, annulées ou remboursées ne sont jamais rouvertes par des notifications ultérieures. Si un second paiement arrive pour une commande déjà payée, la commande n'est pas modifiée. Une note vous demande de rembourser le second paiement dans le Montonio Partner System.

Bloc Montonio payment

La page de commande affiche un bloc Montonio payment avec l'UUID de commande Montonio, l'environnement (avec un badge Sandbox pour les paiements de test), la banque, le statut du paiement, le montant payé et remboursé, l'historique des remboursements et les Montonio notes de la commande.

Remboursements

Dans le bloc Montonio payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif (il n'est conservé que dans la note de commande), puis cliquez sur Refund via Montonio. Confirmez la question Refund this amount through Montonio? 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 limités au montant prélevé par Montonio : après un écart de montant, vous pouvez donc rembourser jusqu'au montant que le client a réellement payé, et non jusqu'au total de la commande. Le remboursement est envoyé à l'environnement dans lequel le paiement a été effectué (sandbox ou production), les clés de cet environnement doivent donc être renseignées. Si Montonio n'accepte pas le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement envoyé est ajouté à l'historique des remboursements et aux notes, avec son statut et l'ID de remboursement Montonio. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut. Les remboursements sont disponibles dès que Montonio a signalé le paiement comme payé.

Montonio confirme ou rejette ensuite chaque remboursement par une notification. Une confirmation est ajoutée aux notes. Si Montonio rejette le remboursement, la note indique que l'argent n'a pas été restitué au client ; vérifiez-le dans le Montonio Partner System et corrigez le remboursement dans PrestaShop.

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 Montonio. Les remboursements effectués dans le Montonio Partner System sont ajoutés aux notes lorsque Montonio les signale. Le statut de la commande et les avoirs ne sont pas modifiés automatiquement. Mettez-les à 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 Montonio Payment est le premier bloc de la page Modules > Module Manager > VibeFox Montonio 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. Sous ces boutons se trouvent la ligne Product: presta-payment-montonio et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant du droit 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, Montonio n'est pas proposé aux clients à l'étape de paiement. 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, donc le moyen de paiement est aussi masqué pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester à l'étape de 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à 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é 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 la licence.

Dépannage

Montonio n'apparaît pas à l'étape de paiement : vérifiez que la licence est active, que Enable/Disable est activé, que les deux clés de l'environnement actuel sont renseignées (Sandbox access key et Sandbox secret key en mode sandbox, Live access key et Live secret key en mode production) et que la devise du panier est EUR ou PLN. La page des réglages affiche un avertissement lorsque des clés manquent ou que la devise de la boutique n'est pas 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 été effectué, mais aucune commande n'a été créée : la notification n'a pas atteint votre boutique. Vérifiez que la boutique est accessible depuis Internet et que les clés des réglages appartiennent à l'environnement du paiement. La commande est aussi créée lorsque le client revient sur la boutique après avoir payé, lorsqu'il clique sur Check again, et lorsqu'il tente de payer à nouveau le même panier.

La notification répond Invalid token : la signature, la date d'expiration ou la clé d'accès du jeton ne correspondaient pas. Vérifiez que la clé d'accès et la clé secrète sont correctement copiées et appartiennent au bon environnement, ainsi que l'exactitude de l'heure du serveur. Un jeton signé avec la clé de l'autre environnement est également rejeté.

La notification répond Payment does not belong to this order : le paiement n'a pas été créé par cette boutique pour ce panier. Cela se produit lorsque deux boutiques utilisent le même compte Montonio et les mêmes numéros de panier.

La notification répond Gateway not configured : aucune clé Montonio n'est renseignée, ou les clés de l'environnement du paiement sont absentes. Saisissez les clés ; Montonio réessaie la notification.

La notification répond Temporarily unavailable : le panier était en cours de confirmation 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é). Montonio réessaie la notification. Consultez le champ Log pour connaître la raison.

Le client voit une erreur lorsqu'il choisit Montonio : consultez le champ Log sur la page du module. This payment method is temporarily unavailable. Please choose another payment method. signifie généralement que les clés sont erronées ou absentes. Montonio could not start the payment. Please check your order details or choose another payment method. signifie que Montonio a refusé les données du paiement ; le journal indique la raison.

La commande est en Montonio payment on hold après le paiement : lisez les notes du bloc Montonio payment (voir Statuts de commande), puis traitez la commande ou remboursez le paiement.

Les paiements sandbox ne confirment pas une commande en production : un paiement sandbox ne finalise jamais une commande tant que la boutique est en mode production ; la commande est mise en attente à la place. Basculez Sandbox mode sur l'environnement souhaité et utilisez les clés de cet environnement.

Le remboursement échoue avec un message concernant l'environnement : le paiement a été effectué dans l'environnement sandbox ou production, et les clés de cet environnement ne sont pas renseignées. Saisissez-les et réessayez.

Pour les développeurs, le module propose les hooks actionWcpMontonioSupportedCurrencies, actionWcpMontonioOrderData et actionWcpMontonioLocale pour modifier les devises prises en charge, les données de paiement et la langue de la page Montonio.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Montonio Payment et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete data est activé, les réglages du module et le journal sont supprimés. Sinon, tous les réglages sont conservés pour une réinstallation ultérieure. Les enregistrements des paiements et remboursements Montonio ainsi que le statut de commande Montonio 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.

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