VibeFox Cardcom 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 de PHP plus anciennes.

HTTPS : votre boutique doit être accessible depuis Internet en HTTPS, pour que Cardcom puisse envoyer la notification de paiement.

Devise : la devise du panier doit être ILS, USD, EUR ou GBP. Pour toute autre devise, le mode de paiement est masqué lors du tunnel de commande.

Compte Cardcom : pour les paiements réels, vous avez besoin d'un compte marchand Cardcom avec un numéro de terminal, un nom d'utilisateur API et un mot de passe API. Les paiements n'ont besoin que du numéro de terminal et du nom d'utilisateur API. Le mot de passe API ne sert qu'aux remboursements depuis PrestaShop. Le mode test fonctionne sans compte Cardcom.

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

4. Activez Enable/Disable, laissez Test Mode activé et cliquez sur Save. Passez une commande test avec la carte 4580 0000 0000 0000, une date d'expiration future quelconque et le CVV 123.

5. Pour les paiements réels, désactivez Test Mode, saisissez le Terminal Number, l'API Username et l'API Password que vous a transmis Cardcom, puis cliquez sur Save.

À l'installation, le module crée le statut de commande Cardcom 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 Cardcom Payment Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche un avertissement tant que le mode test est activé. En mode production, elle vous prévient si le numéro de terminal ou le nom d'utilisateur API manque (Cardcom est alors masqué lors du tunnel de commande), si les champs du mode production contiennent le terminal de test public 1000 / CardTest1994 (Cardcom est alors aussi masqué, car aucun argent réel ne serait débité), et rappelle que sans mot de passe API les remboursements depuis PrestaShop sont impossibles. Elle vous avertit aussi si la devise par défaut de votre boutique n'est pas prise en charge. Lorsque vous enregistrez le mode production avec des identifiants manquants ou de test, un message d'erreur indique que la passerelle reste masquée lors du tunnel de commande tant que vous n'avez pas saisi votre propre numéro de terminal et votre propre nom d'utilisateur API.

Cardcom

Enable/Disable : Enable Cardcom Payment Gateway active ou désactive le mode de paiement. Par défaut : désactivé.

Title : le nom du mode de paiement que voient les clients lors du tunnel de commande. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Credit Card (Cardcom). Obligatoire.

Description : le texte affiché sous le mode de paiement lors du tunnel de commande. Par défaut : Pay securely with your credit card via Cardcom.

Mode test

Le mode test utilise le terminal de test public de Cardcom 1000 (utilisateur API CardTest1994). Aucun argent réel n'est débité et aucun compte Cardcom n'est nécessaire. Carte de test : 4580 0000 0000 0000, date d'expiration future quelconque, CVV 123. En mode test, le tunnel de commande affiche aussi une ligne avec cette carte de test.

Test Mode : active le mode test (terminal 1000, aucun argent réel). Par défaut : activé. Désactivez-le pour accepter des paiements réels avec les identifiants de production ci-dessous. Les remboursements sont toujours envoyés avec les identifiants du mode dans lequel la commande a été payée.

Identifiants de production

Le numéro de terminal, le nom d'utilisateur API et le mot de passe API vous sont fournis par Cardcom avec votre compte marchand : dans le tableau de bord Cardcom, sous les paramètres API, ou auprès du support Cardcom. Ces champs ne sont utilisés qu'en mode production.

Terminal Number : votre numéro de terminal Cardcom. Il ne doit contenir que des chiffres. Si vous saisissez autre chose, une erreur s'affiche et la valeur précédente est conservée.

API Username : votre nom d'utilisateur API Cardcom (ApiName) pour ce terminal. Les espaces sont supprimés à l'enregistrement.

API Password : votre mot de passe API Cardcom. Il n'est nécessaire que pour les remboursements depuis PrestaShop. Le mot de passe enregistré n'est jamais réaffiché : le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.

Clear the saved API password : cochez la case et cliquez sur Save pour supprimer le mot de passe. Un champ vide conserve la valeur enregistrée.

Page de paiement

Notification URL : Cardcom envoie les notifications de paiement (IndicatorUrl) à cette adresse. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_cardcom_payment_gateway/webhook, éventuellement avec un code de langue comme /en/. L'adresse est transmise automatiquement à Cardcom à chaque paiement, avec l'identifiant du panier : il n'y a donc rien à configurer dans Cardcom. Elle doit être accessible depuis Internet en HTTPS.

Operation : ce que fait Cardcom sur la page de paiement.

Max Installments : le nombre maximal de paiements en plusieurs fois que le client peut choisir sur la page Cardcom, de 1 à 36. 1 signifie pas de paiement en plusieurs fois. Par défaut : 1.

Success Order Status : le statut de la commande après un paiement confirmé. La commande est créée directement dans ce statut.

Les paiements qui ne correspondent pas à la commande passent toujours en Cardcom payment on hold.

Avancé

Debug log : enregistre les requêtes API et les notifications dans logs/cardcom_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours journalisées. Les identifiants, les jetons de carte et les données du titulaire ne sont jamais écrits. 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 on Uninstall : lorsque l'option est activée, la désinstallation du module supprime définitivement les réglages et les journaux. Les commandes, les transactions et remboursements Cardcom ainsi que le statut de commande Cardcom payment on hold sont toujours conservés, afin que les anciennes commandes puissent être remboursées après une réinstallation. Par défaut : désactivé.

Tunnel de commande

À l'étape de paiement, le client choisit le mode de paiement (par défaut Credit Card (Cardcom)) et voit la note You will be redirected to the secure Cardcom payment page. Après confirmation, le module crée une page de paiement Cardcom pour le total du panier dans la devise du panier et envoie le client vers cette page. Aucune commande n'existe encore à ce stade. La page s'ouvre en hébreu si la langue du client est l'hébreu, et en anglais sinon. Les produits du panier sont transmis à Cardcom sous forme de nom de produit. Le client saisit les coordonnées de sa carte et, si les paiements en plusieurs fois sont autorisés, choisit le nombre de paiements.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée comme payée qu'après confirmation par Cardcom. Cardcom appelle l'adresse de notification, et le module ne retient de cet appel que le code de la page de paiement. Il vérifie que ce code a été émis par votre boutique pour ce panier, puis interroge Cardcom côté serveur pour obtenir le résultat réel. Si la notification arrive en retard, la même vérification est effectuée lorsque le client revient. La commande est alors créée et le client voit la page standard de confirmation de commande avec Your payment with Cardcom has been received. Si Cardcom n'a pas encore confirmé le paiement au retour du client, une page Payment confirmation affiche Your payment is being confirmed by Cardcom. You will receive an e-mail as soon as it is confirmed. avec un bouton Check again ; la notification crée la commande dès son arrivée.

Si le paiement n'est pas finalisé ou que Cardcom le refuse, le client revient au tunnel de commande avec The card payment was not completed. Please try again or choose a different payment method. Aucune commande n'est créée et le panier est conservé. Le client peut réessayer : chaque tentative obtient une nouvelle page de paiement Cardcom. Un paiement effectué sur une ancienne page de paiement du même panier est toujours reconnu, et un refus sur une ancienne page n'affecte pas une nouvelle tentative.

Si Cardcom ne peut pas ouvrir la page de paiement, le client reste dans le tunnel de commande avec un bref message, par exemple Could not connect to Cardcom. Please try again in a moment., ou un message indiquant que Cardcom n'a pas pu ouvrir la page de paiement, accompagné du code Cardcom, et il peut choisir un autre mode de paiement.

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 n'accepte les paiements par carte que sur la page Cardcom. Il ne gère ni cartes enregistrées ni paiements en un clic, ni abonnements, ne débite pas les jetons enregistrés, n'a aucun réglage de facture ou de reçu Cardcom, pas de Bit, Apple Pay, Google Pay ou PayPal via Cardcom, pas de mode iframe et pas de transactions avec capture différée.

Commandes et remboursements

Statuts de commande

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

Payment accepted, Delivered or Cardcom payment on hold : le paiement a été confirmé. Le statut suit Success Order Status. Le paiement est enregistré avec le numéro d'opération (deal) Cardcom comme identifiant de transaction. Un message privé de la commande affiche la transaction Cardcom et, lorsque Cardcom les transmet, les quatre derniers chiffres de la carte, le numéro de facture et le nombre de paiements. Les paiements test sont marqués Test mode — no real money was charged.

Cardcom payment on hold after payment : Cardcom a confirmé un paiement qui ne correspond pas à la commande, par exemple parce que le panier a été modifié après l'ouverture de la page de paiement, ou parce qu'un autre montant ou une autre devise a été débité. Le message l'explique, et le bloc Cardcom l'affiche sous Needs review. Le paiement est enregistré pour le montant débité par Cardcom lorsque la devise correspond à celle de la commande. Comparez le paiement dans le tableau de bord Cardcom avec la commande, puis traitez la commande ou remboursez le paiement.

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

Si un second paiement réussi arrive pour un panier qui a déjà une commande (par exemple si le client a payé dans deux onglets du navigateur), la commande ne change pas. Un message avertit que le client a peut-être été débité deux fois et vous demande de le rembourser depuis le tableau de bord Cardcom.

Bloc de paiement Cardcom

La page de commande affiche un bloc Cardcom payment avec la transaction, le code de la page de paiement, le statut, la carte, les paiements en plusieurs fois, la facture, le jeton de carte (avec Charge + Save token), le montant débité, le total de la commande et le montant remboursé, un badge Test mode pour les paiements test, ainsi que l'historique des remboursements.

Remboursements

Dans le bloc Cardcom payment, saisissez le montant (le montant non encore remboursé est pré-rempli), éventuellement un motif, puis cliquez sur Refund via Cardcom. Confirmez la question Refund this amount through Cardcom? This cannot be undone. Les remboursements totaux et partiels sont pris en charge, et plusieurs remboursements partiels peuvent être effectués pour une même commande. Vous devez disposer du droit de modifier les commandes ; l'accès aux pages des modules n'est pas nécessaire. Les remboursements sont effectués dans le montant et la devise débités par Cardcom : après un écart de montant ou de devise, vous pouvez donc rembourser jusqu'à concurrence de ce que le client a réellement payé, et non le total de la commande. Le remboursement est envoyé avec les identifiants du mode dans lequel la commande a été payée : les commandes test sont remboursées sur le terminal de test Cardcom même après le passage en mode production, et les commandes réelles utilisent toujours vos identifiants de production. Les remboursements réels nécessitent l'API Username et l'API Password. Si Cardcom n'accepte pas 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 messages de la commande, avec la transaction de remboursement Cardcom et le motif. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut.

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 Cardcom. Les remboursements effectués dans le tableau de bord Cardcom 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 Cardcom Payment Gateway est le premier bloc de Modules > Module Manager > VibeFox Cardcom Payment 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-cardcom 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, Cardcom n'est pas affiché aux clients lors du 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 mode de paiement est donc masqué aussi pour vous. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester lors du tunnel de commande. 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 le support nécessitent un renouvellement. Le statut est vérifié à nouveau 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 licence.

Dépannage

Cardcom n'apparaît pas dans le tunnel de commande : vérifiez que la licence est active, que Enable/Disable est activé et que la devise du panier est ILS, USD, EUR ou GBP. En mode production, vérifiez que Terminal Number et API Username sont renseignés avec vos propres identifiants, et non avec le terminal de test 1000 / CardTest1994. La page des réglages affiche un avertissement lorsque quelque chose manque. 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 : Cardcom n'a pas pu joindre votre boutique, par exemple à cause d'un pare-feu, d'une protection par mot de passe ou d'un site de développement local. L'adresse de notification doit être accessible depuis Internet en HTTPS. La commande est aussi créée lorsque le client revient dans la boutique après le paiement. Activez Debug log et consultez le champ Log sur la page du module.

La notification répond Missing or invalid lowprofilecode or Unknown lowprofilecode for this order : l'appel ne contenait pas de code de page de paiement émis par votre boutique pour ce panier. Rien n'est modifié.

La notification répond Gateway not configured or Indicator check failed : les identifiants du mode dans lequel la page de paiement a été créée sont manquants, ou Cardcom n'a pas pu être joint pour la vérification. Rien n'est modifié ; le paiement est à nouveau vérifié lorsque le client revient dans la boutique.

La notification répond Busy, retry : 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é). Activez Debug log pour voir la raison.

La notification répond ReturnValue mismatch or Terminal mismatch : Cardcom a signalé un paiement pour un autre panier ou un autre terminal. Rien n'est modifié. Vérifiez que le Terminal Number est bien le terminal de votre compte.

Le client voit Payment error: this currency is not supported by Cardcom.: la devise du panier n'est pas ILS, USD, EUR ou GBP.

Le client voit Card payment is temporarily unavailable. Please choose another payment method.: le mode production est activé, mais le numéro de terminal ou le nom d'utilisateur API manque, ou les champs du mode production contiennent le terminal de test public.

Le client voit une erreur lorsqu'il choisit Cardcom : activez Debug log et consultez le champ Log. Les problèmes de connexion et les codes d'erreur Cardcom y sont écrits.

La commande est Cardcom payment on hold after payment : lisez le message de la commande ou Needs review dans le bloc Cardcom payment. Le montant ou la devise payé(e) ne correspondait pas à la commande. Traitez la commande ou remboursez le paiement.

Le remboursement échoue avec API username and API password are required for refunds : saisissez l'API Password (et l'API Username) dans les réglages, puis réessayez.

Le remboursement échoue avec Could not connect to Cardcom : vérifiez le tableau de bord Cardcom avant de réessayer, car le remboursement a peut-être été effectué ou non.

Pour les développeurs, le README répertorie le hook actionCardcomSupportedCurrencies, qui étend la liste des devises (n'ajoutez que les devises activées sur votre terminal Cardcom), et actionCardcomLowProfileParams, qui modifie les paramètres de la page de paiement.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Cardcom Payment Gateway et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete on Uninstall est activé, les réglages et les journaux 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 Cardcom ainsi que le statut de commande Cardcom payment on hold sont toujours conservés, afin que les commandes payées auparavant puissent être remboursées après une réinstallation. Les commandes existantes conservent leurs messages de paiement et leurs identifiants de transaction.

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