VibeFox Helcim 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 et PCI DSS : les coordonnées de carte sont saisies sur votre page de paiement et envoyées depuis votre serveur à Helcim en HTTPS. Elles ne sont jamais stockées ni journalisées, mais elles transitent par votre serveur. Votre boutique a donc besoin d'un certificat SSL, et votre hébergement doit respecter la norme PCI DSS (SAQ D).

Compte Helcim : un compte marchand Helcim au Canada ou aux États-Unis et un jeton d'API doté du droit de traiter des transactions (voir Configuration). Helcim traite le CAD et l'USD. Un compte de test (développeur) Helcim est facultatif pour les tests.

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échargement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Helcim 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, puis cliquez sur Activate (voir Clé de licence).

4. Dans Helcim, ouvrez All Tools > Integrations > API Access Configuration, créez un accès API doté du droit de traiter des transactions (achats, préautorisations, captures, remboursements) et copiez son jeton.

5. Collez le jeton dans Live API token, et le jeton de votre compte de test Helcim dans Test API token si vous en avez un.

6. Choisissez le Transaction type et les Account currencies, activez Enable / Disable et cliquez sur Save. Pour tester d'abord, activez Test mode et payez avec votre compte de test ; désactivez ensuite ce mode.

À l'installation, le module crée deux statuts de commande, Helcim payment authorized et Helcim payment on hold. PrestaShop active un nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez le limiter dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Helcim Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit si la devise par défaut de votre boutique ne figure pas parmi les Account currencies, et, tant que le mode de paiement est activé, si le jeton d'API du mode actuel est vide. Dans ce cas, le mode de paiement est masqué sur la page de paiement.

Helcim

Enable / Disable : Enable Helcim Gateway active ou désactive le mode de paiement. Par défaut : off.

Title : le titre du mode de paiement affiché sur la page de paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Credit card (Helcim). Obligatoire.

Description : la description du mode de paiement affichée sur la page de paiement. Par défaut : Pay securely with your credit card.

Identifiants API

Dans Helcim, allez dans All Tools > Integrations > API Access Configuration, créez un accès API et copiez son jeton. Accordez-lui le droit de traiter des transactions pour les achats, les préautorisations, les captures et les remboursements. Les comptes de test Helcim utilisent la même adresse d'API que les comptes réels : le mode test utilise donc simplement le jeton de votre compte de test Helcim.

Live API token : le jeton d'API de votre compte Helcim réel. Il est utilisé lorsque le mode test est désactivé.

Test mode : utilise le Test API token (compte de test Helcim). Les paiements, captures et remboursements sont envoyés à votre compte de test Helcim, et les clients voient un avertissement de mode test. Les captures et remboursements d'une commande utilisent toujours le jeton du mode avec lequel la commande a été payée. Par défaut : off.

Test API token : le jeton d'API de votre compte de test (développeur) Helcim. Il est utilisé lorsque le mode test est activé.

Les jetons enregistrés ne sont plus jamais affichés. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.

Clear saved tokens : cochez un jeton et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

Paiement

Transaction type : la manière dont la carte est débitée.

Account currencies : les devises que votre compte Helcim peut traiter. Les commandes sont toujours débitées dans la devise du panier. Le mode de paiement est masqué sur la page de paiement pour les autres devises.

Avancé

Debug log : écrit les requêtes et réponses de l'API dans logs/wc_hlg_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les numéros de carte sont réduits aux 4 derniers chiffres. Le CVC, la date d'expiration, les jetons, les noms, les adresses, les e-mails et les adresses IP ne sont jamais journalisés. Les erreurs (paiements refusés ou échoués, erreurs de l'API, captures et remboursements échoués) sont toujours journalisées, même lorsque cette option est désactivée. Par défaut : off.

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

Delete data on uninstall : lorsqu'elle est activée, la désinstallation du module supprime les réglages de la passerelle et ses fichiers journaux. Les transactions, remboursements et statuts de commande Helcim sont toujours conservés, si bien que les commandes payées auparavant peuvent encore être capturées et remboursées après une réinstallation. Par défaut : off.

Page de paiement

À l'étape de paiement, le client choisit le mode de paiement (par défaut Credit card (Helcim), avec une icône de carte) et saisit Card Number, Expiry (MM/YY), CVC et Cardholder Name dans le formulaire situé dessous. En mode test, le formulaire affiche TEST MODE — payments go to a Helcim test account, no real charges are made. Lorsque le client passe la commande, le module vérifie la somme de contrôle du numéro de carte, la validité de la date d'expiration (qui ne doit pas être échue), que le CVC comporte 3 ou 4 chiffres et que le nom est renseigné. Les erreurs s'affichent sur la page de paiement, et rien n'est envoyé à Helcim.

Votre serveur envoie ensuite la carte à Helcim, en achat ou en préautorisation, pour le total du panier dans la devise du panier. L'adresse de facturation, le téléphone et l'e-mail sont envoyés pour la vérification d'adresse. Le paiement apparaît dans Helcim avec un numéro de facture composé du numéro de panier, de -PS et d'un court code. Helcim répond dans la même requête. La commande n'est créée qu'après l'approbation de la transaction par Helcim, et le client arrive sur la page standard de confirmation de commande. Aucune commande n'existe avant cela.

Une seule tentative de paiement par panier s'exécute à la fois, et un panier qui a déjà une commande n'est jamais débité à nouveau. Chaque tentative utilise une clé d'idempotence. Si Helcim ne répond pas, aucune commande n'est créée, et une nouvelle tentative dans les 5 minutes renvoie le résultat Helcim d'origine au lieu de débiter la carte deux fois. Si le paiement a été approuvé mais que la commande n'a pas pu être créée, la tentative suivante du même panier crée la commande sans débiter à nouveau la carte.

Messages que le client peut voir sur la page de paiement : Your card was declined. Please check the card details or use another card. lorsque Helcim refuse ; Payment failed: avec le motif donné par Helcim pour les autres demandes rejetées ; We could not confirm your payment with the card processor. Please try again in a minute; if the problem persists, contact us before using another card. lorsque Helcim ne répond pas ; This payment method is temporarily unavailable. Please choose another payment method. lorsque le jeton d'API est absent ou rejeté par Helcim ; Your payment is already being processed. Please wait a moment and check your e-mail before trying again. en cas de double envoi ; Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. lorsque le paiement a été approuvé mais que la commande n'a pas pu être créée. Le panier est conservé. Les détails techniques sont envoyés au journal.

Le module n'utilise ni HelcimPay.js ni Helcim.js : les coordonnées de carte transitent donc par votre serveur. Il ne gère ni cartes enregistrées, ni abonnements, ni paiements ACH ou bancaires, ni Apple Pay, Google Pay ou 3-D Secure, ni webhooks Helcim.

Commandes et remboursements

Statuts de commande

No order : la carte a été refusée, Helcim n'a pas répondu, ou le client n'a pas encore payé. Seul le panier existe. Les refus et les erreurs sont inscrits dans le journal.

Payment accepted : un achat a été approuvé, ou une préautorisation a été capturée. Le paiement est enregistré avec l'identifiant de transaction Helcim, et une note affiche l'identifiant de transaction, le code d'approbation, le type de carte, les 4 derniers chiffres et le mode.

Helcim payment authorized : une préautorisation a été approuvée. Les fonds sont seulement retenus. Capturez-les ou libérez-les par un remboursement total.

Helcim payment on hold : Helcim a approuvé une transaction, mais le montant, la devise ou l'identifiant de transaction de sa réponse ne correspondent pas au panier, par exemple après une approbation partielle ou si le panier a changé pendant le paiement. La note indique Helcim response verification FAILED. Pour un achat, le paiement est enregistré avec le montant réellement débité par Helcim. Vérifiez la transaction dans Helcim avant de traiter la commande.

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

Canceled : une préautorisation non capturée a été libérée. Le client n'a pas été débité.

Si une seconde transaction est approuvée pour un panier qui a déjà une commande, la commande n'est pas modifiée. Une note vous demande de la vérifier et de l'annuler ou de la rembourser dans Helcim.

Bloc de paiement Helcim

La page de commande affiche un bloc Helcim payment avec l'identifiant de transaction (et l'identifiant de la préautorisation après une capture), le type de transaction et l'état de la capture, le numéro de facture, la carte et le code d'approbation, le montant approuvé, le total de la commande et le montant remboursé, un badge Test mode pour les paiements de test, l'historique des remboursements et les Helcim notes de la commande. La capture et les remboursements exigent le droit de modifier les commandes.

Capture

Pour une commande en Helcim payment authorized, cliquez sur Capture payment dans le bloc et confirmez Capture the pre-authorized amount through Helcim? Le total actuel de la commande, moins les remboursements, est capturé. Il peut être inférieur au montant préautorisé, mais pas supérieur. La capture utilise le jeton du mode avec lequel la commande a été payée. Après une capture réussie, la commande passe en Paiement accepté, et le paiement est enregistré avec l'identifiant de transaction de la capture. Si la capture échoue, le bloc affiche le motif et l'ajoute aux notes.

Remboursements

Dans le bloc, saisissez le montant (le montant non encore remboursé est pré-rempli), éventuellement un motif, puis cliquez sur Refund via Helcim. Confirmez Refund this amount through Helcim? This cannot be undone. Les remboursements totaux et partiels d'un achat ou d'une préautorisation capturée sont pris en charge, dans la limite du montant réellement débité par Helcim. Ainsi, après une approbation partielle, vous ne pouvez pas rembourser plus que ce que le client a payé. Pour une préautorisation non capturée, le bouton est Release pre-authorization : seul le montant total peut être libéré, la retenue est supprimée et la commande passe à l'état Annulé.

Le remboursement est envoyé dans le mode avec lequel la commande a été payée, donc le jeton de ce mode doit être défini. Il n'est comptabilisé que si Helcim l'approuve. Si Helcim le refuse, 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 l'identifiant de transaction de remboursement Helcim. Un remboursement total passe la commande en Refunded. Un remboursement partiel ne modifie pas le statut. Une nouvelle tentative après un dépassement de délai ne rembourse pas deux fois.

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 Helcim. Le module ne reçoit pas de webhooks Helcim : les captures, remboursements et annulations effectués dans le tableau de bord Helcim ne sont pas répercutés dans PrestaShop. Effectuez-les donc depuis la page de commande.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Helcim Gateway est le premier bloc de la page Modules > Module Manager > VibeFox Helcim 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-helcim 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, Helcim n'est pas proposé aux clients sur la page 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 boutique PrestaShop ne sait pas que vous êtes connecté au back office, donc le mode de paiement est masqué aussi pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester sur la page de paiement. Un rappel apparaît dans Modules > Module Manager, sur l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà effectués sont conservés, et les captures et remboursements continuent de fonctionner.

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

Helcim n'apparaît pas sur la page de paiement : vérifiez que la licence est active, que Enable / Disable est activé, que le mode actuel dispose de son jeton d'API (Live API token, ou Test API token en mode test) et que la devise du panier fait partie des Account currencies. La page de réglages affiche un avertissement lorsque le jeton est absent ou que la devise de la boutique n'est pas autorisée. 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 client a vu « We could not confirm your payment » : Helcim n'a pas répondu, la carte a donc peut-être été débitée. Regardez le champ Log : l'erreur indique le panier et la facture Helcim. Vérifiez cette facture dans Helcim avant de débiter à nouveau le client. Une nouvelle tentative dans les 5 minutes renvoie le résultat d'origine et ne débite pas deux fois.

Les clients voient « This payment method is temporarily unavailable » : le jeton d'API du mode actuel est vide ou a été rejeté par Helcim. Le journal indique de vérifier le jeton et ses droits. Assurez-vous que l'accès API dispose du droit de traiter des transactions.

Paiement échoué pour un motif Helcim : Helcim a rejeté la demande, par exemple à cause de la carte ou des coordonnées de facturation. Le journal contient les détails.

Le client a vu « Your payment was received, but the order could not be completed » : Helcim a approuvé le paiement, mais PrestaShop n'a pas pu créer la commande (par exemple parce que le module était désactivé). Le journal indique le motif. Lorsque le client soumet à nouveau le même panier, la commande est créée à partir du paiement approuvé, sans second débit.

Commande en Helcim payment on hold : lisez les notes dans le bloc Helcim. La réponse de Helcim ne correspondait pas au panier (échec de la vérification de la réponse). Vérifiez la transaction dans Helcim, puis traitez la commande ou remboursez le paiement.

Capture impossible : le montant à capturer doit être supérieur à 0 et ne pas dépasser le montant préautorisé, et le jeton du mode avec lequel la commande a été payée doit être défini.

Le remboursement échoue : lisez le message. Une préautorisation non capturée ne peut être libérée qu'en totalité. Un message concernant le mode signifie que le jeton du mode avec lequel la commande a été payée est vide. Un remboursement refusé n'est pas enregistré.

Paiements de test : le mode test envoie les paiements, captures et remboursements vers votre compte de test Helcim. Les commandes conservent le mode avec lequel elles ont été payées : changer de mode plus tard ne déplace donc pas leurs captures et remboursements vers l'autre compte.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Helcim 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 Helcim ainsi que les statuts de commande Helcim payment authorized et Helcim payment on hold sont toujours conservés, si bien que les commandes payées auparavant peuvent encore être capturées et remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Helcim est une marque de son détenteur respectif. Ce module n'est ni affilié à Helcim, ni approuvé par Helcim.