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

HTTPS : votre boutique doit être accessible en HTTPS depuis Internet, afin que Comgate puisse envoyer la notification en arrière-plan.

Devise : CZK, EUR, PLN, HUF, USD, GBP, RON, HRK, NOK ou SEK. Pour les autres devises et pour les totaux inférieurs au minimum de Comgate, le mode de paiement est masqué. Les paiements en HUF sont arrondis au forint entier, comme l'exige Comgate.

Compte Comgate : vous avez besoin du Merchant ID et du secret (mot de passe pour la communication en arrière-plan) de la connexion de votre boutique dans le portail client de Comgate, ainsi que de l'URL de notification qui y est configurée (voir Configuration). Comgate utilise le même Merchant ID et le même secret pour les paiements de test et les paiements réels.

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

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

4. Saisissez le Merchant ID et le Secret du portail client de Comgate, puis configurez-y l'URL de notification (voir Configuration).

5. Activez Enable / Disable et cliquez sur Save. Gardez Test Mode activé pour un paiement d'essai, puis désactivez-le.

À l'installation, le module crée le statut de commande Comgate payment on hold. PrestaShop propose un nouveau mode 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 Comgate Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit si Comgate est activé mais que le Merchant ID ou le secret manque (le mode de paiement est alors masqué au paiement tant que les deux ne sont pas renseignés) et si la devise par défaut de la boutique n'est pas prise en charge par Comgate. Lorsque le mode test est activé, elle affiche Test mode is on: payments are created as Comgate test payments and no money is charged. Turn it off before going live.

Comgate

Enable / Disable : Enable Comgate Payment Gateway active ou désactive le mode de paiement. Default: off.

Title : le nom du mode de paiement affiché aux clients au moment du paiement. C'est aussi le nom enregistré dans la commande. Default: Comgate. Obligatoire.

Description : le texte affiché sous le mode de paiement au moment du paiement. Default: Pay securely via Comgate — cards, bank transfers, wallets and more. En mode test, TEST MODE: no real money is charged. y est ajouté, ou affiché seul si la description est vide.

Connexion à Comgate

Récupérez l'identifiant de boutique (Merchant ID) et le mot de passe (secret) dans le portail client de Comgate, à Integration > shop connection settings. Au même endroit, réglez l'URL for passing the payment result (notification en arrière-plan) sur l'URL affichée dans Notification URL de cette section. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_comgate_gateway/webhook, éventuellement avec un code de langue comme /en/. Copiez l'URL exactement telle qu'elle est affichée dans les réglages. Comgate l'appelle après chaque paiement ; le module revérifie alors le paiement via l'API de statut de Comgate avant de modifier quoi que ce soit. Les URL de retour pour le client sont envoyées avec chaque paiement. Si le portail demande aussi des URL de retour (payé, annulé, en attente), utilisez la seconde URL affichée dans cette section, qui se termine par return?id=${id}&refId=${refId}.

Merchant ID : l'identifiant de boutique e-commerce (merchant) chez Comgate.

Secret : le mot de passe pour la communication en arrière-plan (secret) de cette connexion de boutique. Un secret enregistré n'est jamais réaffiché. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.

Effacer le secret enregistré : cochez la case et cliquez sur Save pour supprimer le secret enregistré. Un champ vide conserve la valeur enregistrée.

Test Mode : crée des paiements de test (aucun argent n'est débité). Comgate utilise le même Merchant ID et le même secret pour les paiements de test et les paiements réels ; les paiements de test sont marqués test=true. Les remboursements sont toujours envoyés dans le mode du paiement d'origine. Default: on.

Page de paiement

Payment Methods : les modes de paiement Comgate que le client peut choisir. Seuls les modes activés pour votre boutique dans Comgate sont affichés.

Language : la langue de la page de paiement Comgate. Automatic (shop language, English as fallback) (par défaut) ou l'une des 26 langues disponibles.

Commandes

Order Status After Payment : le statut attribué lorsque Comgate confirme le paiement.

Les paiements qui ne correspondent pas à la commande, les paiements de test en mode réel et les paiements pré-autorisés vont toujours en Comgate payment on hold.

Avancé

Debug Log : écrit les requêtes API et les notifications dans logs/comgate_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Le secret et les données personnelles ne sont jamais journalisés. Les erreurs sont toujours journalisées. Default: off.

Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.

Delete Data on Uninstall : si cette option est activée, la désinstallation du module supprime les réglages de la passerelle et le journal. Les commandes et leurs identifiants de transaction Comgate sont toujours conservés. Default: off.

Paiement

À l'étape de paiement, le client choisit le mode de paiement (par défaut Comgate) et confirme la commande. Le module crée le paiement chez Comgate pour le total du panier dans la devise du panier, puis redirige le client vers la page de paiement de Comgate. L'adresse e-mail et le nom du client sont transmis à Comgate, et le paiement est libellé Cart avec le numéro du panier. Une adresse e-mail valide est obligatoire. Sur la page de Comgate, le client paie avec l'un des modes que vous avez autorisés. À ce stade, aucune commande n'existe encore.

Après le paiement, le client revient sur votre boutique. La commande n'est marquée comme payée qu'après confirmation par Comgate : le module lit le paiement via l'API de statut de Comgate, aussi bien à l'arrivée de la notification en arrière-plan qu'au retour du client. La commande est alors créée et le client voit la page standard de confirmation de commande. Si la commande a été mise en attente, la page ajoute Your payment is being reviewed. We will contact you if anything else is needed. Si une commande pré-autorisée a été annulée par la suite, la page affiche Your Comgate payment was not completed. Please contact us about this order.

Si le paiement n'est pas encore confirmé au retour du client, par exemple un virement bancaire en cours, une page Payment confirmation affiche Comgate has not confirmed your payment yet. Your order will be created automatically as soon as the payment is confirmed — please do not pay again. avec un bouton Check again et un bouton Back to checkout.

Si le paiement est annulé ou expire, le client revient au paiement avec le message The Comgate payment was cancelled or has expired. You can try again or choose another payment method. Le panier est conservé. Chaque nouvelle tentative vérifie d'abord la précédente, afin qu'un paiement déjà abouti ne soit pas débité deux fois, et la tentative précédente est annulée chez Comgate si elle est encore ouverte. Un paiement tardif d'une tentative plus ancienne crée tout de même la commande.

Si Comgate ne peut pas démarrer le paiement, le client reste sur la page de paiement avec un court message, par exemple The Comgate payment could not be started. Please try again or choose another payment method., indiquant que Comgate ne peut pas accepter ce montant ou cette devise, ou que le mode de paiement Comgate sélectionné n'est pas disponible. La raison technique est écrite dans le journal.

La notification fonctionne pendant que la boutique est en mode maintenance et n'est pas bloquée par la restriction géographique de votre boutique.

Le module ne traite que des paiements uniques, sur la page de Comgate. Il ne propose ni paiements récurrents, ni abonnements, ni cartes enregistrées, ni tunnel de paiement Comgate intégré, ni boutons Apple Pay ou Google Pay sur votre site (ils sont disponibles sur la page Comgate), ni capture ou annulation de pré-autorisations depuis PrestaShop. Sans la notification, le statut du paiement n'est pas interrogé automatiquement ; il n'est vérifié qu'au retour du client.

Commandes et remboursements

Statuts de commande

Pas encore de commande : le client a été envoyé à Comgate et n'a pas encore payé, ou Comgate signale le paiement comme en attente. Seul le panier existe.

Payment accepted or Delivered : Comgate a signalé le paiement comme PAID avec le même montant et la même devise. Le statut suit Order Status After Payment. Le paiement est enregistré avec l'identifiant de transaction Comgate. Les paiements de test reçoivent la note Comgate test payment — no money was charged.

Comgate payment on hold : le montant ou la devise payé diffère de la commande, un paiement de test a été confirmé alors que la boutique est en mode réel (aucun argent n'a été reçu), ou le paiement n'est qu'autorisé (pré-autorisation sur votre compte Comgate). Un paiement autorisé devient automatiquement payé lorsque vous le capturez dans le portail Comgate. La note explique la raison.

Canceled : un paiement autorisé a été annulé ou a expiré chez Comgate. Si Comgate confirme ensuite le paiement, la commande est rouverte comme payée avec une note vous invitant à vérifier le stock avant l'expédition.

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

Si Comgate signale un autre paiement PAID pour une commande déjà payée, la commande n'est pas modifiée. Une note vous demande de le vérifier dans le portail Comgate et de rembourser le doublon. Une confirmation rejouée ne rouvre jamais une commande remboursée.

Bloc de paiement Comgate

La page de commande affiche un bloc Comgate payment avec l'identifiant de transaction, le statut Comgate, le montant payé, le total de la commande et le montant remboursé, un badge Test mode pour les paiements de test, la raison d'un examen, l'historique des remboursements et les Comgate notes de la commande.

Remboursements

Dans le bloc Comgate payment, saisissez le montant (le montant non encore remboursé est pré-rempli), éventuellement un motif, puis cliquez sur Refund via Comgate. Confirmez la question Refund this amount through Comgate? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez avoir le droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. Le remboursement est adressé à la transaction Comgate payée et envoyé dans le mode (test ou réel) du paiement d'origine. Comgate ne rembourse que les paiements PAID, à hauteur du montant payé au maximum ; les remboursements en HUF doivent porter sur des forints entiers. Si Comgate refuse le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec le montant, la transaction Comgate et le motif. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut.

Les remboursements ne sont possibles que pour les commandes payées. Une commande mise en attente après un écart de montant ou de devise ne peut pas être remboursée depuis PrestaShop ; remboursez-la dans le portail Comgate. 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 Comgate. Les remboursements effectués dans le portail Comgate ne sont pas signalés à la boutique.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Comgate Gateway est le premier bloc de Modules > Module Manager > VibeFox Comgate 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 retirer la clé de cette boutique. En dessous figurent la ligne Product: presta-payment-comgate 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, Comgate n'est pas affiché aux clients au moment du 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 de PrestaShop ne sait pas que vous êtes connecté au back-office, donc le mode de paiement est aussi masqué pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au moment du paiement. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas touché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 le support 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

Comgate n'apparaît pas au paiement : vérifiez que la licence est active, que Enable / Disable est activé, que le Merchant ID et le Secret sont renseignés, que la devise du panier est prise en charge et que le total de la commande n'est pas inférieur au minimum de Comgate (par exemple 1 CZK, 0,10 EUR ou 100 HUF). 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 : Comgate n'a pas livré la notification en arrière-plan. Vérifiez l'URL for passing the payment result dans le portail Comgate (exactement la Notification URL des réglages), que votre boutique est accessible en HTTPS depuis Internet, ainsi que le journal (activez Debug Log). Comgate renvoie les notifications non livrées ; le module répond par une erreur chaque fois qu'il n'en a pas traité une, elle sera donc renvoyée. La commande est aussi créée lorsque le client revient sur la boutique.

La notification répond Invalid merchant or secret : le Merchant ID ou le secret des réglages ne correspond pas à la connexion de boutique du portail Comgate.

La notification répond Gateway not configured : le Merchant ID ou le secret est vide dans les réglages. Comgate réessaiera une fois ces champs renseignés.

La notification répond Unknown transaction, Order not found ou Reference mismatch : la notification concerne un paiement que cette boutique n'a pas créé pour ce panier. Rien n'est modifié.

La notification répond Status verification failed, Status verification rejected ou Busy, retry later : l'API de statut de Comgate est injoignable, a rejeté la requête, ou le panier était en cours de traitement par une autre requête au même moment. Busy est aussi la réponse lorsque la commande n'a pas pu être créée ; la raison figure dans le journal. Comgate réessaie la notification.

L'URL de notification affiche code=1&message=POST%20required dans le navigateur : c'est normal. L'URL n'accepte que les requêtes provenant de Comgate.

Le client voit We could not verify the Comgate payment : le lien de retour ne correspondait pas au panier. Si un débit a eu lieu, la notification crée tout de même la commande. Vérifiez le paiement dans le portail Comgate avant que le client ne paie à nouveau.

Le client voit The order total is below the minimum amount accepted by Comgate ou A valid billing e-mail address is required for Comgate payments : le panier ne peut pas être payé avec Comgate en l'état.

La commande est en Comgate payment on hold après le paiement : lisez les notes du bloc Comgate payment. Le montant ou la devise payé était différent, un paiement de test est arrivé en mode réel, ou le paiement n'est qu'autorisé. Vérifiez le paiement dans le portail Comgate, puis finalisez ou remboursez la commande manuellement.

Le remboursement échoue : lisez le message affiché dans le bloc. Comgate rejected the refund: the amount exceeds the refundable amount. signifie que le montant est supérieur à ce qui reste remboursable ; un paiement dont le statut n'est pas PAID ne peut pas être remboursé. Comgate could not be reached. The refund was not made — please try again later. signifie un problème de connexion.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Comgate 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 de la passerelle 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 Comgate ainsi que le statut de commande Comgate 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.

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