VibeFox MakeCommerce 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.

Accès Internet à votre boutique : MakeCommerce envoie les notifications de paiement à votre boutique, le site doit donc être accessible depuis Internet. Un pare-feu ou une authentification de base peut les bloquer. Le mode maintenance et la restriction par pays de votre boutique ne les bloquent pas.

Compte MakeCommerce : vous avez besoin du Shop ID et de la Secret key, disponibles dans le Merchant Portal de MakeCommerce (Settings > API). Les environnements de test et de production ont des comptes et des clés distincts. Les modes de paiement et les devises disponibles sont définis par votre contrat MakeCommerce. Les devises à trois décimales, comme KWD ou BHD, ne sont pas proposées.

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 MakeCommerce 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 le Shop ID et la Secret key de l'environnement de test et, pour les paiements réels, les clés de production (voir Configuration). Rien n'a besoin d'être configuré dans le Merchant Portal.

5. Activez Enable/Disable et cliquez sur Save. Testez un paiement avec Test mode activé, puis désactivez-le pour accepter les paiements réels.

À l'installation, le module crée le statut de commande MakeCommerce payment on hold. PrestaShop propose le nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les limiter dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox MakeCommerce Payment > Configure. Chaque section possède son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche Test mode is on: payments are created in the MakeCommerce test environment and no real money is charged. tant que le mode test est activé. Elle vous avertit lorsque la méthode est activée mais que le Shop ID ou la Secret key de l'environnement actuel est vide, et lorsque la devise par défaut de la boutique ne peut pas être encaissée par MakeCommerce. Dans les deux cas, la méthode est masquée à l'étape de paiement. Les espaces sont supprimés des clés à l'enregistrement.

MakeCommerce

Enable/Disable : Enable MakeCommerce payments active ou désactive le mode de paiement. Par défaut : désactivé.

Title : le nom du mode de paiement que voient les clients à l'étape de paiement. Il est aussi enregistré comme nom du mode de paiement dans la commande. Par défaut : Bank link or card (MakeCommerce). Obligatoire.

Description : le texte affiché sous le mode de paiement à l'étape de paiement. Par défaut : Pay with your Estonian, Latvian, Lithuanian or Finnish bank, or by card. You will be redirected to the secure MakeCommerce payment page.

Compte MakeCommerce

Le Shop ID et la Secret key se trouvent dans le Merchant Portal de MakeCommerce, sous Settings > API. Le portail de test et le portail de production ont des comptes et des clés distincts. La section contient des liens vers les deux portails et vers la page d'inscription de MakeCommerce.

Test mode : utilise l'environnement de test de MakeCommerce (aucun argent réel n'est débité). Les nouveaux paiements sont créés dans l'environnement sélectionné, avec ses clés. Chaque commande garde en mémoire l'environnement dans lequel elle a été payée : les vérifications de statut et les remboursements s'y adressent toujours. Lorsqu'il est activé, les clients voient TEST MODE — MakeCommerce test environment, no real money is charged. sous le mode de paiement. Par défaut : activé.

Test Shop ID : le Shop ID de votre compte de test, au format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Test Secret key : la Secret key de votre compte de test.

Live Shop ID : le Shop ID de votre compte de production.

Live Secret key : la Secret key de votre compte de production.

Les clés secrètes enregistrées ne sont plus jamais 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 secret keys : cochez une clé et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Notifications de paiement

Rien n'a besoin d'être configuré dans le Merchant Portal. Callback URLs affiche, à titre indicatif, l'adresse de retour ou d'annulation du client et l'adresse des notifications de paiement. Chaque transaction transporte ses propres URL de retour, d'annulation et de notification, construites à partir de ces adresses, avec le numéro du panier et une clé ajoutée. MakeCommerce envoie un message signé à l'URL de notification (de serveur à serveur) et, via le navigateur du client, à l'URL de retour ou d'annulation. La signature est vérifiée avec la Secret key de l'environnement dans lequel la transaction a été créée. Les messages sans signature valide sont rejetés.

Le module gère les statuts de transaction MakeCommerce suivants :

Le paiement est également confirmé lorsque le client revient dans la boutique. Si le client revient sans message signé, le module demande le statut à l'API MakeCommerce.

Avancé

Debug log : enregistre les appels à l'API et les notifications de paiement dans logs/wc_mkc_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours enregistrées. Les clés et les données clients ne sont jamais enregistré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 : lorsqu'il est activé, la désinstallation du module supprime les réglages du module et le journal. Les commandes et leurs données de paiement MakeCommerce sont toujours conservées. Par défaut : désactivé.

Page de commande

À l'étape de paiement, le client choisit le mode de paiement (par défaut Bank link or card (MakeCommerce)) et confirme. Le module crée une transaction MakeCommerce pour le total du panier, dans la devise du panier, et envoie le client sur la page de paiement MakeCommerce. Là, le client choisit un lien bancaire ou une carte. L'e-mail et le pays du client sont transmis à MakeCommerce, et la page s'ouvre dans la langue de la boutique lorsque MakeCommerce la prend en charge (estonien, anglais, letton, lituanien, finnois, russe, allemand, polonais), sinon en anglais. Aucune commande n'existe encore à ce stade.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée payée qu'après confirmation par MakeCommerce : par la notification signée ou par le retour signé du client, avec une vérification de la transaction via l'API MakeCommerce. La commande est alors créée et le client voit la page standard de confirmation de commande, avec Your MakeCommerce payment has been received. Si la commande a été mise en attente pour examen, la page affiche Your MakeCommerce payment was received and is being reviewed by the shop.

Si le paiement est approuvé mais pas encore finalisé, ou si MakeCommerce est injoignable, une page Payment confirmation affiche We could not confirm your payment yet. If you completed it, your order will be updated automatically — please do not pay again. avec les boutons Check again et Back to checkout. La notification crée la commande dès que le paiement est finalisé.

Si le client annule sur la page MakeCommerce, ou si le paiement expire ou échoue, il revient à la page de commande avec un message, par exemple The payment was cancelled. You can try again or choose another payment method., The payment session expired. Please try again. ou The payment was not completed. Please try again or choose another payment method. Le panier est conservé et le client peut payer à nouveau. Chaque tentative correspond à une nouvelle transaction MakeCommerce. Un ancien lien de paiement du même panier fonctionne toujours, et le panier ne peut pas être payé deux fois pour deux commandes.

Si MakeCommerce ne peut pas démarrer le paiement, le client reste sur la page de commande avec MakeCommerce is temporarily unavailable. Please try again in a moment or choose another payment method. ou MakeCommerce could not start the payment for this order. Please choose another payment method or contact us. La raison technique est écrite dans le journal.

La banque ou la carte est choisie sur la page MakeCommerce, pas sur votre page de commande. Le module ne prend en charge ni cartes enregistrées, ni paiements récurrents ou abonnements, et n'inclut pas les services d'expédition MakeCommerce (consignes automatiques, étiquettes).

Commandes et remboursements

Statuts de commande

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

Payment accepted : le paiement a été confirmé. Il est enregistré avec l'identifiant de transaction MakeCommerce, et une note indique le montant, la transaction, l'environnement et le mode de vérification (API MakeCommerce ou notification signée).

MakeCommerce payment on hold : le montant ou la devise payés différaient du panier (par exemple, si le panier a été modifié après le début du paiement), le montant était absent, la transaction chez MakeCommerce n'était pas encore définitive alors qu'elle était indiquée comme terminée, ou le paiement est arrivé après l'annulation de la commande. La note l'explique. Si la devise payée est celle de la commande, le montant réellement payé est enregistré sur la commande. Une transaction présentant une divergence ne paie jamais la commande par la suite ; une transaction qui n'était pas encore définitive finalise la commande lorsque MakeCommerce la signale comme terminée. Vérifiez la transaction dans le Merchant Portal, puis traitez la commande ou remboursez le paiement.

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

Si un second paiement arrive pour une commande déjà payée, la commande n'est pas modifiée. Une note vous invite à rembourser le doublon dans le Merchant Portal de MakeCommerce.

Bloc paiement MakeCommerce

La page de commande affiche un bloc MakeCommerce payment regroupant toutes les transactions MakeCommerce du panier (date, identifiant de transaction, un badge Test pour les paiements de test, montant, statut et résultat MakeCommerce), les montants payés et remboursés, l'historique des remboursements et les MakeCommerce notes de la commande. Les boutons du bloc nécessitent seulement le droit de modifier les commandes, et non l'accès aux modules.

Check MakeCommerce payment status : interroge l'API MakeCommerce pour le statut des transactions du panier (les plus récentes en premier), applique ce statut et ajoute une note avec le résultat. Utilisez-le lorsqu'un client affirme avoir payé mais que la commande n'a pas été finalisée.

Remboursements

Dans le bloc MakeCommerce payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via MakeCommerce. Confirmez la question Refund this amount via MakeCommerce? Les remboursements totaux et partiels sont pris en charge. Les remboursements sont limités au montant et à la devise de la transaction MakeCommerce : après une divergence de montant, vous pouvez donc rembourser jusqu'au montant réellement payé par le client, et non le total de la commande. Le remboursement est envoyé à l'environnement dans lequel le paiement a été effectué (test ou production), les clés de cet environnement doivent donc être renseignées. Le motif est transmis à MakeCommerce comme commentaire de remboursement ; sans motif, le commentaire est Refund for order suivi de la référence de la commande. Si MakeCommerce refuse le remboursement, le bloc affiche l'erreur, une note est ajoutée et aucun remboursement n'est enregistré. Si MakeCommerce traite encore le paiement, le message est MakeCommerce is still processing this payment — try the refund again later. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec l'identifiant de remboursement MakeCommerce. Un remboursement total place la commande en Refunded. Un remboursement partiel ne change pas le statut. Les remboursements sont disponibles une fois que MakeCommerce a confirmé le paiement.

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 MakeCommerce.

Les remboursements effectués dans le Merchant Portal arrivent avec le statut de la transaction et sont ajoutés aux notes. Le statut de la commande et les avoirs ne sont pas modifiés automatiquement.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox MakeCommerce Payment est le premier bloc de Modules > Module Manager > VibeFox MakeCommerce Payment > Configure, au-dessus des réglages. Collez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date de fin de validité de la licence 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 retirer la clé de cette boutique. En dessous figurent la ligne Product: presta-payment-makecommerce 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 : celui 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, MakeCommerce n'est pas affiché 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 : le mode de paiement est donc 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 que vous travaillez 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

MakeCommerce n'apparaît pas à l'étape de paiement : vérifiez que la licence est active, que Enable/Disable est activé et que l'environnement actuel dispose de ses clés : Test Shop ID et Test Secret key en mode test, Live Shop ID et Live Secret key en mode production. Vérifiez que la devise du panier comporte au maximum deux décimales. 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 : les notifications n'ont pas pu atteindre la boutique, par exemple à cause d'un pare-feu ou d'une authentification de base. La commande est aussi créée lorsque le client revient dans la boutique ou clique sur Check again. Vérifiez que les clés de l'environnement dans lequel le paiement a été effectué sont renseignées : la notification est vérifiée avec la Secret key de cet environnement, et sans elle MakeCommerce reçoit une erreur et réessaie. Activez le Debug log pour voir les notifications.

La commande est en MakeCommerce payment on hold : lisez les MakeCommerce notes dans le bloc de la page de commande (voir Statuts de commande), vérifiez la transaction dans le Merchant Portal, puis traitez la commande ou remboursez le paiement.

Les notifications sont rejetées : un message avec une mauvaise signature, pour un autre panier, une autre boutique ou une transaction non créée pour le panier est rejeté, et rien n'est modifié. Vérifiez que le Shop ID et la Secret key appartiennent au même compte et au même environnement MakeCommerce.

Le client voit une erreur en choisissant MakeCommerce : activez le Debug log et consultez le champ Log sur la page du module. Une devise que MakeCommerce ne peut pas encaisser affiche MakeCommerce cannot process payments in suivi du code de la devise.

Le remboursement échoue avec un message concernant l'environnement : la commande a été payée dans l'environnement de test ou de production, et les clés de cet environnement ne sont pas configurées. Saisissez-les et réessayez.

Le remboursement échoue avec No MakeCommerce transaction ID found for this order : la commande n'a pas de paiement MakeCommerce confirmé. Remboursez-la dans le Merchant Portal.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox MakeCommerce 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. S'il est désactivé, tous les réglages sont conservés pour une réinstallation ultérieure. Les transactions et remboursements MakeCommerce ainsi que le statut de commande MakeCommerce 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.

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