VibeFox Helcim for WooCommerce — Aide
Prérequis
WordPress : 5.8 ou ultérieur.
WooCommerce : 7.0 ou ultérieur, installé et actif. Sans WooCommerce, l'extension refuse de s'activer.
PHP : 8.0 ou ultérieur.
HTTPS et PCI DSS : les coordonnées de carte sont saisies sur votre page de paiement et transmises de votre serveur à Helcim via HTTPS. Elles ne sont jamais stockées ni consignées dans les journaux, 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 disposant des autorisations de traitement des transactions (voir Configuration). Helcim traite le CAD et l'USD. Un compte de test Helcim (développeur) est facultatif pour effectuer des tests.
Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un domaine.
Installation
1. Dans WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez également téléverser le dossier wcp_helcim_gateway dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Dans Helcim, ouvrez All Tools > Integrations > API Access Configuration, créez un accès API avec les autorisations de traitement des transactions (achats, préautorisations, captures, remboursements) et copiez son jeton.
4. Ouvrez les réglages : WooCommerce > Settings > Payments > Helcim > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page Extensions.
5. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.
6. Collez le jeton dans Live API token, et le jeton de votre compte de test Helcim dans Test API token si vous en possédez un.
7. Choisissez le Transaction type et les Account currencies, activez Enable / Disable et enregistrez. Pour tester au préalable, activez Test mode et effectuez un paiement avec votre compte de test, puis désactivez-le.
Configuration
Tous les réglages sont regroupés sur une seule page : WooCommerce > Settings > Payments > Helcim. Au-dessus des champs, la page vous avertit lorsque la devise de la boutique ne fait pas partie des Account currencies et, tant que la passerelle est activée, lorsque le jeton d'API du mode actuel est vide. Dans les deux cas, la passerelle est masquée lors du paiement. Dans la liste des modes de paiement, la passerelle est signalée comme nécessitant une configuration tant que le mode actuel n'a pas de jeton.
Enable / Disable: Enable Helcim Gateway active ou désactive le mode de paiement. Par défaut : désactivé.
Title: titre du mode de paiement affiché lors du paiement. Par défaut : Credit card (Helcim).
Description: description du mode de paiement affichée lors du paiement. Par défaut : Pay securely with your credit card.
Identifiants API
Dans Helcim, rendez-vous dans All Tools > Integrations > API Access Configuration, créez un accès API et copiez son jeton. Attribuez-lui les droits de traitement des transactions pour les achats, préautorisations, captures et remboursements. Les comptes de test Helcim utilisent la même adresse d'API que les comptes de production ; le mode test utilise donc simplement le jeton de votre compte de test Helcim.
Live API token: jeton d'API de votre compte Helcim de production. Utilisé lorsque le mode test est désactivé.
Test mode: Use the Test API token (Helcim test account). Les paiements, captures et remboursements sont envoyés à votre compte de test Helcim, et les clients voient un avis de mode test. Les remboursements et captures d'une commande utilisent toujours le jeton du mode dans lequel la commande a été payée. Par défaut : désactivé.
Test API token: jeton d'API de votre compte de test Helcim (développeur). Utilisé lorsque le mode test est activé.
Paiement
Transaction type: mode de débit de la carte.
Account currencies: devises que votre compte Helcim peut traiter. Les commandes sont toujours débitées dans la devise de la commande. La passerelle est masquée lors du paiement pour les autres devises.
Avancé
Debug log: Log API requests and responses vers WooCommerce > Status > Logs, source wcp_helcim_gateway. Les numéros de carte sont tronqués 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 enregistrés. Par défaut : désactivé.
Delete data on uninstall: Remove the gateway settings, its own options (wc_hlg_*) and its log files when the plugin is deleted. Par défaut : désactivé.
Paiement
Le client choisit le mode de paiement (par défaut Credit card (Helcim)) et saisit Card Number, Expiry (MM/YY), CVC et Cardholder Name sur votre page de paiement. Les icônes de Visa, Mastercard, American Express et Discover s'affichent à côté du titre. En mode test, le formulaire affiche TEST MODE — payments go to a Helcim test account, no real charges are made. Avant l'envoi, l'extension vérifie la somme de contrôle du numéro de carte, que la date d'expiration est valide et non échue, que le CVC comporte 3 ou 4 chiffres et que le nom est renseigné.
Lorsque la commande est passée, votre serveur envoie la carte à Helcim sous la forme d'un achat ou d'une préautorisation pour le montant total de la commande dans la devise de celle-ci. L'adresse de facturation, le téléphone et l'e-mail sont transmis pour vérification de l'adresse. Le paiement apparaît dans Helcim avec un numéro de facture composé du numéro de commande et d'un code court. Helcim répond dans la même requête. La commande n'est marquée comme payée qu'après l'approbation de la transaction par Helcim et la vérification que le montant et la devise approuvés correspondent à la commande. Le client accède ensuite à la page de commande reçue.
Une seule tentative de paiement est exécutée à la fois par commande, et une commande déjà payée n'est jamais débitée une seconde fois. Chaque tentative utilise une clé d'idempotence. Si Helcim ne répond pas, la commande reste avec le statut « En attente de paiement », et une nouvelle tentative dans un délai de 5 minutes renvoie le résultat Helcim d'origine au lieu de débiter la carte deux fois.
Messages que le client peut voir : Your card was declined. Please check the card details or use another card. lorsque Helcim refuse le paiement ; Payment failed: avec le motif de Helcim pour les autres requêtes 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 manquant ou rejeté ; Your payment is already being processed. Please wait a moment and check your e-mail before trying again. en cas de double envoi. Les détails techniques sont consignés dans les notes de commande et le journal.
Le mode de paiement fonctionne sur la page de paiement classique, sur le bloc Paiement (avec les mêmes champs de carte) et sur la page Pay for order. Il est compatible avec le stockage des commandes haute performance de WooCommerce (HPOS).
L'extension n'utilise ni HelcimPay.js ni Helcim.js, de sorte que les données de la carte transitent par votre serveur. Elle ne prend en charge ni les cartes enregistrées, ni les abonnements, ni les paiements bancaires ou ACH, ni Apple Pay, Google Pay ou 3-D Secure, et ne reçoit aucun webhook Helcim.
Commandes et remboursements
Statuts de commande
Pending payment: le paiement a été refusé ou n'a pas encore été confirmé. Si Helcim n'a pas répondu, la note de commande vous invite à vérifier la facture Helcim avant de débiter à nouveau le client.
Processing: un achat a été approuvé ou une préautorisation a été capturée. Les commandes ne contenant que des produits virtuels téléchargeables passent au statut « Terminée », le comportement par défaut de WooCommerce. La note de commande indique l'identifiant de transaction, le code d'approbation, le type de carte, les 4 derniers chiffres et le mode. L'identifiant de transaction correspond à l'identifiant de transaction Helcim.
On hold (pre-authorization): les fonds sont seulement retenus. Capturez-les à l'aide de l'action de commande ou libérez-les via un remboursement intégral.
On hold after payment: Helcim a approuvé une transaction, mais le montant, la devise ou l'identifiant de transaction dans sa réponse ne correspondent pas à la commande. La note indique Helcim response verification FAILED. Vérifiez la transaction dans Helcim avant de traiter la commande.
Capture
Ouvrez la commande (statut « En attente »), sélectionnez l'action de commande Capture Helcim pre-authorization et cliquez sur Update. Le montant total actuel de la commande, déduction faite des remboursements, est capturé. Il peut être inférieur au montant autorisé, mais pas supérieur. La capture utilise le jeton du mode dans lequel la commande a été payée. Après une capture réussie, la commande passe au statut « En cours » et l'identifiant de transaction devient celui de la capture. En cas d'échec de la capture, le motif s'affiche et est consigné dans les notes de commande.
Remboursements
Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Credit card (Helcim) (le bouton affiche votre Title). Les remboursements intégraux et partiels d'un achat ou d'une préautorisation capturée sont pris en charge. Une préautorisation non capturée ne peut être remboursée que dans son intégralité : la retenue est libérée et le client n'est pas débité. Le remboursement est envoyé selon le mode dans lequel la commande a été payée, le jeton de ce mode doit donc être renseigné. Il n'est pris en compte que si Helcim l'approuve. Si Helcim le refuse, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est consigné dans les notes de commande avec l'identifiant de transaction de remboursement Helcim. Une nouvelle tentative après un dépassement de délai n'effectue aucun double remboursement.
L'extension ne reçoit aucun webhook Helcim. Les captures, remboursements et annulations effectués dans le tableau de bord Helcim ne sont pas répercutés dans WooCommerce : effectuez-les donc depuis WooCommerce.
Clé de licence
L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de la page WooCommerce > Settings > Payments > Helcim. Collez la clé dans License key et cliquez sur Activate. Le bloc indique l'état, par exemple la date jusqu'à laquelle la licence est active ainsi que votre domaine. Utilisez Check now pour revérifier l'état, Change key pour renseigner une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.
Une clé fonctionne sur un domaine. Supprimer la clé d'un site ne libère pas son emplacement de domaine. Libérez l'emplacement dans votre compte vibefox.net.
Sans clé active, Helcim n'est pas affiché aux clients lors du paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. Les gestionnaires de la boutique connectés continuent de voir le mode de paiement, accompagné de la mention (unlicensed — visible to admins only), ce qui vous permet de configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Extensions et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées : les captures et les remboursements continuent de fonctionner.
Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. L'état est revérifié automatiquement en arrière-plan.
Dépannage
Helcim n'apparaît pas lors du paiement : vérifiez que la licence est active, que Enable / Disable est activé, que le mode actuel possè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. Sur la page Pay for order, la devise de la commande est prise en compte. La page des réglages affiche un avertissement dans les deux cas.
Helcim n'a pas répondu et la commande reste au statut « En attente de paiement » : la carte a peut-être été débitée. Lisez la note de commande et vérifiez la facture dans Helcim avant de débiter à nouveau le client. Une nouvelle tentative dans un délai de 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. La note de commande indique de vérifier le jeton et ses autorisations. Assurez-vous que l'accès API dispose des droits de traitement des transactions.
Le paiement a échoué avec un motif Helcim : Helcim a rejeté la requête, par exemple en raison de la carte ou des informations de facturation. La note de commande en précise les détails.
La commande est « En attente » après le paiement : lisez la note de commande. La commande a été préautorisée et attend sa capture, ou la réponse de Helcim ne correspondait pas à la commande (échec de la vérification de la réponse).
La capture est impossible : le montant à capturer doit être supérieur à 0 et ne pas dépasser le montant autorisé, et le jeton du mode dans lequel la commande a été payée doit être configuré.
Le remboursement échoue : lisez le message. Une préautorisation non capturée ne peut être remboursée que dans son intégralité. Un message concernant le mode indique que le jeton du mode dans 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 à votre compte de test Helcim. Les commandes conservent le mode dans lequel elles ont été payées : changer de mode ultérieurement ne bascule pas leurs captures et remboursements vers l'autre compte.
Le bloc de licence affiche une erreur : suivez le message affiché dans le bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé sur le nouveau domaine. Si le serveur de licences est inaccessible, l'extension continue de fonctionner avec le dernier état connu.
Pour les développeurs : le filtre wc_hlg_supported_currencies modifie la liste des devises, et wc_hlg_card_brands modifie les icônes de cartes lors du paiement.
Désinstallation
Lors de la désactivation de l'extension, toutes les données sont conservées. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et l'état de la licence de cette extension sont toujours supprimés. Les réglages de la passerelle, les options propres à l'extension et les journaux ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils sont conservés en vue d'une réinstallation ultérieure. Les données de commande font partie de l'historique des commandes et ne sont jamais supprimées. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.
Helcim est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à Helcim ni approuvée par Helcim.