VibeFox Transbank 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 antérieures de PHP.

Devise : peso chilien (CLP). Webpay Plus n'encaisse que des pesos entiers ; réglez donc la précision de la devise CLP sur 0 dans International > Localization > Currencies. Pour les paniers dans une autre devise, le mode de paiement n'est pas affiché.

Compte Transbank : pour les paiements réels, vous avez besoin d'un commerce Webpay Plus standard (capture immédiate) avec son Commerce Code de production et son API Key Secret. Transbank vous fournit le Commerce Code une fois votre affiliation approuvée, et l'API Key Secret après le processus de validation de l'intégration (voir la documentation développeurs de Transbank). Pour les tests, aucun identifiant n'est nécessaire. Les codes de commerce Webpay Plus Mall, Oneclick et de capture différée ne sont pas pris en charge.

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 Transbank 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. Activez Enable / Disable et cliquez sur Save. Testez un paiement avec Integration (test) mode activé, en utilisant les cartes de test de la documentation développeurs de Transbank.

5. Pour passer en production, saisissez votre Production Commerce Code et votre Production API Key Secret, désactivez Integration (test) mode et cliquez sur Save.

Aucune URL de retour ni aucun webhook n'a besoin d'être configuré chez Transbank. Le module envoie son URL de retour avec chaque transaction.

À l'installation, le module crée le statut de commande Transbank payment on hold. PrestaShop active le nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les restreindre dans Payment > Preferences ; la devise CLP doit rester autorisée pour le module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Transbank Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit lorsque la production est sélectionnée mais que le Commerce Code ou l'API Key de production est absent ou invalide (Webpay est alors masqué au paiement), lorsque la devise par défaut de la boutique n'est pas CLP (le mode de paiement est masqué pour les autres devises), et lorsque CLP a des décimales (les totaux sont arrondis aux pesos entiers). Tant que le mode intégration est activé, la page indique que les paiements vont à l'environnement d'intégration de Transbank avec le code de commerce de test public et qu'aucun argent réel n'est débité.

Transbank Webpay Plus

Enable / Disable : Enable Transbank Webpay Plus 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 au paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Webpay Plus. Obligatoire : si vous enregistrez avec un titre vide, Enter a title for the payment method. s'affiche.

Description : le texte affiché sous le mode de paiement au moment du paiement. Par défaut : Pay with credit, debit or prepaid card via Webpay.

Environnement et identifiants

Le texte de la section renvoie vers la documentation développeurs de Transbank et explique quand Transbank fournit les identifiants de production.

Integration (test) mode : les paiements vont à l'environnement d'intégration de Transbank avec son code de commerce de test public (597055555532), renseigné automatiquement. Les identifiants de production ci-dessous ne sont pas utilisés et aucun argent réel n'est débité. Par défaut : activé. Désactivez-le pour passer en production. Tant qu'il est activé, les clients voient TEST MODE : environnement d'intégration. Aucun débit réel. au-dessus de la description du mode de paiement.

Production Commerce Code : votre code de commerce de production (Tbk-Api-Key-Id) : 12 chiffres commençant par 5970. Si le vôtre compte 8 chiffres, saisissez-le tel quel ; le module ajoute le préfixe 5970 à l'enregistrement. Les espaces et autres caractères sont supprimés. Les codes de commerce de test publics de Transbank ne sont pas acceptés en production.

Production API Key Secret : le Tbk-Api-Key-Secret de votre commerce de production. Gardez-le secret. Les espaces sont supprimés à l'enregistrement. Une clé enregistrée n'est jamais réaffichée : le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que si vous voulez la modifier.

Clear saved API key : cochez Production API Key Secret et cliquez sur Save pour supprimer la clé enregistrée. Un champ vide conserve la valeur enregistrée.

URL de retour

Return from Webpay : l'adresse à laquelle Transbank renvoie le client, affichée à titre indicatif. Rien n'est à configurer chez Transbank : le module envoie cette URL avec chaque transaction. Elle doit être accessible aux clients ; le mode maintenance ne la bloque pas.

Avancé

Debug log : enregistre les requêtes API et les retours dans logs/wc_tbk_debug.log.php, dans le dossier du module. Ce fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements sont toujours journalisés, même lorsque cette option est désactivée. Aucune donnée de carte, clé API ni jeton complet n'est journalisé. 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 on uninstall : si activé, la désinstallation du module supprime les réglages de la passerelle et le journal. Les données de commande sont conservées. Par défaut : désactivé.

Test et production

Integration (test) mode détermine où vont les nouveaux paiements. Chaque paiement retient son environnement : la confirmation et les remboursements d'un paiement vont toujours à l'environnement (intégration ou production) et avec les identifiants avec lesquels il a été créé, même si vous changez de mode ensuite.

Paiement

À l'étape de paiement, le client choisit le mode de paiement (par défaut Webpay Plus, avec le logo Webpay) et confirme. Le module crée une transaction Transbank pour le total du panier en pesos entiers (un total avec décimales est arrondi au peso le plus proche) et envoie le client vers une courte page Redirecting to Webpay. Please wait..., qui le transfère vers le formulaire Webpay. Sans JavaScript, le client clique sur Proceed to Webpay. Sur Webpay, le client paie par carte de crédit, de débit ou prépayée. Aucune commande n'existe encore à ce stade.

Lorsque le client revient, le module confirme (commit) la transaction auprès de Transbank, de serveur à serveur. La commande n'est marquée payée qu'après la confirmation de Transbank : la réponse doit être approuvée, et le montant, le buy order et la session doivent correspondre à ce que la boutique a envoyé pour cette tentative. La commande est alors créée et le client voit la page standard de confirmation de commande avec Your Webpay payment has been received. Pour une commande en attente, la page affiche Your Webpay payment was received and is being reviewed by the shop.

Si l'appel de confirmation échoue, par exemple sur un délai dépassé, le module demande à Transbank le statut de la transaction. Si ce statut reste inconnu, aucune commande n'est créée et le client voit We could not confirm your Webpay payment with Transbank. Please try again in a moment; if your card was charged, contact us before paying again. Si une autre requête confirme le même panier à ce moment-là, ou si Transbank a approuvé le paiement mais que la commande ne peut pas encore être créée, le client voit une page Payment confirmation avec Your Webpay payment is being confirmed. Please do not pay again — check again in a moment. et un bouton Check again. La commande est alors créée à partir de la réponse enregistrée, sans seconde confirmation.

Si le client annule sur Webpay, ou si le formulaire Webpay expire ou signale une erreur, rien n'est débité. Le client revient au paiement avec un message, par exemple You cancelled the Webpay payment. Nothing was charged — you can try again or choose another payment method. Une carte refusée affiche Your Webpay payment was rejected and nothing was charged. Please try again or choose another payment method. Le panier est conservé, et chaque nouvelle tentative est une nouvelle transaction Webpay.

Si le panier a changé après le début du paiement (par exemple dans un autre onglet, ou si un bon de réduction du panier a cessé d'être valide et que PrestaShop l'a retiré), la transaction n'est pas confirmée, donc Transbank ne la débite pas. Le client voit Your cart changed after the Webpay payment was started. The payment was not confirmed, so it was not charged — please pay again. Si le panier a déjà une commande (payée par une autre tentative ou un autre mode de paiement), un retour tardif n'est pas confirmé non plus, et le client voit This order can no longer be paid (it was cancelled or already paid). Your Webpay payment was not confirmed, so it was not charged. si cette commande n'est pas payée.

Si Webpay ne peut pas démarrer le paiement, le client reste au paiement avec un bref message, par exemple Could not connect to Webpay. Please try again in a moment. ou Webpay payments are not available at the moment. Please choose another payment method. La raison technique est écrite dans le journal.

Le retour depuis Webpay fonctionne pendant que la boutique est en mode maintenance et n'est pas bloqué par la restriction géographique de votre boutique.

Transbank n'a pas de webhook de paiement : le résultat est traité lorsque le client revient de Webpay. Si le client ferme le navigateur sur Webpay et ne revient jamais, la transaction n'est pas confirmée et aucune commande n'est créée ; selon Transbank, les transactions non confirmées ne sont pas réglées. Le module ne gère ni Webpay Plus Mall, ni cartes enregistrées Oneclick, ni abonnements, ni capture différée, ni conversion de devise.

Commandes et remboursements

Statuts de commande

No order yet : le client a été envoyé vers Webpay et n'a pas payé, a annulé, a laissé expirer le formulaire, la carte a été refusée ou le paiement n'a pas encore pu être confirmé. Seul le panier existe.

Payment accepted : Transbank a approuvé le paiement. Le paiement est enregistré avec le jeton Webpay comme identifiant de transaction, et une note indique le code d'autorisation, les quatre derniers chiffres de la carte, le buy order, le montant, le type de paiement et le nombre de mensualités.

Transbank payment on hold : Transbank a autorisé un paiement qui ne correspond pas à la commande (montant, buy order ou session), ou un bon de réduction du panier a cessé d'être valide après l'approbation du paiement par Transbank, et PrestaShop l'a retiré. Le paiement est enregistré avec le montant débité par Transbank, et la note énumère les écarts. Vérifiez le portail Transbank, puis traitez la commande ou remboursez le paiement.

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

Si Webpay renvoie un paiement pour un panier qui a déjà une commande, le paiement n'est pas confirmé et une note sur cette commande vous demande de vérifier le portail Transbank si le client signale un débit. Les commandes existantes ne sont pas affectées par les tentatives ultérieures.

Bloc Transbank Webpay Plus

La page de commande affiche un bloc Transbank Webpay Plus avec le buy order et son environnement, le statut du paiement, le code d'autorisation, la carte et le type de paiement avec le nombre de mensualités, le montant débité et remboursé, un badge Integration pour les paiements de test, l'historique des remboursements, les Webpay attempts of the cart et les Transbank notes de la commande.

Remboursements

Dans le bloc Transbank Webpay Plus, saisissez le montant en CLP (le montant pas encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Transbank. Confirmez la question Refund this amount via Transbank? Les remboursements totaux et partiels sont pris en charge en pesos entiers. Vous devez avoir le droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. Un montant partiel avec décimales est refusé avec Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. Le reliquat final d'un total de commande avec décimales est arrondi comme le débit. Les remboursements sont possibles jusqu'au montant débité par Transbank : après un écart, vous pouvez donc rembourser ce que le client a réellement payé. Le remboursement est effectué dans l'environnement où le paiement a été réalisé ; pour un paiement en production, les identifiants de production doivent donc être renseignés.

Transbank répond par une annulation de transaction (REVERSED) ou une nullification (NULLIFIED). Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec le montant, le type, le code d'autorisation et le solde restant chez Transbank. Un remboursement total passe la commande en Refunded. Un remboursement partiel ne modifie pas le statut. Si Transbank n'accepte pas le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré.

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 Transbank. Les remboursements effectués dans le portail Transbank ne sont pas importés dans PrestaShop.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Transbank Gateway est le premier bloc de Modules > Module Manager > VibeFox Transbank Gateway > Configure, au-dessus des réglages. Saisissez la clé dans License key, puis 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. Sous ceux-ci figurent la ligne Product: presta-payment-transbank 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-le dans votre compte vibefox.net.

Sans clé active, Webpay Plus n'est pas affiché aux clients au 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 masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au 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 au retour du client depuis Webpay, et les remboursements depuis la page de commande 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é 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 la licence.

Dépannage

Webpay Plus n'apparaît pas au paiement : vérifiez que la licence est active, que Enable / Disable est activé, que la devise du panier est CLP et que, avec le mode intégration désactivé, un Production Commerce Code valide (12 chiffres commençant par 5970) et une Production API Key Secret sont enregistrés. La page des réglages affiche un avertissement pour chaque condition manquante. Dans Payment > Preferences, vérifiez que le module est autorisé pour CLP, le pays du client et le groupe du client.

Le paiement est passé, mais aucune commande n'a été créée : Transbank n'a pas de webhook ; la commande n'est donc créée que lorsque le client revient de Webpay. Si le client a fermé le navigateur sur Webpay, la transaction n'a pas été confirmée et, selon Transbank, n'est pas réglée. Activez Debug log, consultez le champ Log et vérifiez la transaction dans le portail Transbank.

Le client voit We could not confirm your Webpay payment with Transbank : l'appel de confirmation a échoué et le statut n'a pas pu être vérifié. Aucune commande n'a été créée et la raison figure dans le journal. Le client peut réessayer dans un instant. Si le portail Transbank affiche la transaction comme autorisée, contactez le client avant qu'il ne paie à nouveau.

Le client voit Your cart changed after the Webpay payment was started : le total du panier différait de la transaction, par exemple à cause d'une modification dans un autre onglet ou d'un bon de réduction expiré. Rien n'a été débité ; le client paie le nouveau total.

Le client voit une erreur en choisissant Webpay Plus : activez Debug log et consultez le champ Log sur la page du module. Webpay payments are not available at the moment indique en général des identifiants de production incorrects. Could not connect to Webpay signifie que Transbank est injoignable. Transbank Webpay only supports payments in CLP (Chilean Peso) signifie que le panier est dans une autre devise.

Les totaux et les remboursements diffèrent de quelques pesos : la devise CLP a des décimales. Webpay n'encaisse que des pesos entiers, donc les totaux sont arrondis. Réglez la précision de CLP sur 0 dans International > Localization > Currencies.

La commande est en Transbank payment on hold après le paiement : lisez les notes du bloc Transbank Webpay Plus (voir Statuts de commande), puis traitez la commande ou remboursez le paiement.

Le remboursement échoue avec The production Commerce Code / API Key are missing : le paiement a été réalisé en production et les identifiants de production ne sont pas enregistrés. Saisissez-les et réessayez.

Le remboursement échoue avec Transbank refused the refund ou Transbank did not approve the refund : Transbank ne l'a pas accepté ; le message indique la raison, ou le type et le code réponse renvoyés. Aucun montant n'a été remboursé. Vérifiez la transaction dans le portail Transbank.

Le remboursement échoue avec Another request is processing this order : la commande était en cours de remboursement ou de confirmation au même moment. Réessayez dans un instant.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Transbank 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 future réinstallation. Les tentatives Webpay et les remboursements des commandes, ainsi que le statut de commande Transbank 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.

Transbank et Webpay sont des marques de leurs titulaires respectifs. Ce module n'est ni affilié à Transbank ni approuvé par Transbank.