VibeFox Transbank for WooCommerce — Aide

Prérequis

WordPress : 6.0 ou ultérieur.

WooCommerce : 8.0 ou ultérieur, installé et activé. L'extension ne s'active pas sans lui.

PHP : 8.0 ou ultérieur.

Devise de la boutique : peso chilien (CLP). Webpay Plus ne facture que des pesos entiers ; réglez donc Number of decimals sur 0 dans WooCommerce > Settings > General. Dans les boutiques dont la devise est différente, le moyen de paiement n'est pas affiché.

Compte Transbank : pour les paiements réels, il vous faut un commerce Webpay Plus standard (capture immédiate) avec son Commerce Code de production et sa API Key Secret. Transbank vous fournit le Commerce Code lorsque votre affiliation est 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier wcp_transbank_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Réglez la devise de la boutique sur peso chilien et Number of decimals sur 0 dans WooCommerce > Settings > General.

4. Ouvrez les réglages : WooCommerce > Settings > Payments > Transbank Webpay Plus > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page Plugins.

5. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

6. Activez Enable / Disable et testez un paiement avec Integration (test) mode activé, à l'aide des cartes de test de la documentation développeurs de Transbank.

7. Pour passer en production, saisissez votre Production Commerce Code et votre Production API Key Secret, décochez Integration (test) mode et enregistrez.

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

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Transbank Webpay Plus. Au-dessus des champs, la page vous avertit lorsque la production est sélectionnée mais que le Production Commerce Code ou l'API Key est absent ou invalide (Webpay est alors masqué sur la page de paiement), lorsque la devise de la boutique n'est pas CLP (le moyen de paiement est masqué) et lorsque les prix en CLP ont des décimales (les totaux sont arrondis aux pesos entiers). Tant que le mode d'intégration est activé, la page affiche Integration (test) environment : aucun argent réel n'est débité. Après l'enregistrement, les avertissements suivent les nouveaux réglages. Dans la liste des moyens de paiement, la passerelle est signalée comme nécessitant une configuration lorsque la production est sélectionnée sans identifiants valides.

Général

Enable / Disable : Enable Transbank Webpay Plus payments active ou désactive le moyen de paiement. Par défaut : désactivé.

Title : le nom du moyen de paiement que voient les clients au paiement. Par défaut : Webpay Plus.

Description : le texte affiché sous le moyen 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 à la documentation développeurs de Transbank et explique quand Transbank vous fournit les identifiants de production.

Integration (test) mode : Use the Transbank integration environment. Les paiements sont envoyés à 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écochez-le pour passer en production.

Production Commerce Code : votre code de commerce de production (Tbk-Api-Key-Id) : 12 chiffres, commençant par 5970. Si le vôtre comporte 8 chiffres, saisissez-le tel quel ; l'extension 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.

Avancé

Debug log : Log API requests and returns (errors are always logged). Les détails sont écrits dans WooCommerce > Status > Logs, source wcp_transbank_gateway ; le champ comporte un lien view logs. Les erreurs et avertissements sont 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é.

Delete data on uninstall : Remove the gateway settings and logs when the plugin is deleted (order data is kept). Par défaut : désactivé.

Test et production

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

Paiement

Le client choisit le moyen de paiement (par défaut Webpay Plus) et passe la commande. En mode d'intégration, la page de paiement affiche TEST MODE : Integration environment. Aucun débit réel. L'extension crée une transaction Transbank pour le montant total de la commande en pesos entiers (un total avec décimales est arrondi au peso le plus proche) et envoie le client sur une courte page Redirecting to Webpay. Please wait..., qui le redirige 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.

Lorsque le client revient, l'extension confirme (commit) la transaction auprès de Transbank de serveur à serveur. La commande n'est marquée payée qu'après 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. Le client voit ensuite la page Commande reçue. Si l'appel de confirmation échoue, par exemple sur un délai dépassé, l'extension demande à Transbank le statut de la transaction. Si ce statut reste inconnu, la commande n'est pas modifié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 le client annule sur Webpay, si le formulaire Webpay expire ou signale une erreur, rien n'est débité. La commande reste en attente de paiement et le client revient sur la page Pay for order 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 client peut payer à nouveau depuis cette même page. Chaque nouvelle tentative correspond à une nouvelle transaction Webpay.

Chaque tentative Webpay est confirmée au plus une fois. Recharger la page de retour, utiliser le bouton Précédent du navigateur ou un second retour au même moment ne confirment jamais deux fois et ne modifient jamais la commande. Si une commande n'a plus besoin de paiement (déjà payée par une autre tentative, annulée ou remboursée), un retour tardif n'est pas confirmé, donc Transbank ne le débite pas. 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 Webpay ne peut pas démarrer le paiement, le client voit un court 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 enregistrée dans le journal.

Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).

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 sans jamais revenir, la transaction n'est pas confirmée et la commande reste en attente ; selon Transbank, les transactions non confirmées ne sont pas réglées. L'extension 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

Pending payment : le client a été envoyé vers Webpay et n'a pas encore payé, a annulé, a laissé expirer le formulaire, ou le paiement n'a pas encore pu être confirmé. Une note enregistre chaque tentative close avec son buy order.

Processing or Completed : Transbank a approuvé le paiement. Le statut est défini par WooCommerce : En cours, ou Terminée pour les commandes ne comportant que des produits virtuels téléchargeables. La note de commande indique le code d'autorisation, les quatre derniers chiffres de la carte, le buy order, le montant, le type de paiement et le nombre d'échéances. L'ID de transaction est le jeton Webpay.

On hold : Transbank a autorisé un paiement qui ne correspond pas à la commande (montant, buy order ou ID de session), par exemple parce que la commande a été modifiée après le début du paiement. La note énumère les écarts. Vérifiez le portail Transbank, puis remboursez ou finalisez la commande.

Failed : le paiement a été refusé. Rien n'a été débité. La note indique le code et le statut de réponse.

Si Webpay renvoie un paiement pour une commande déjà payée, annulée ou remboursée, le paiement n'est pas confirmé et une note vous invite à 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.

Remboursements

Le bouton de remboursement n'est proposé que pour les commandes payées par Webpay. Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Webpay Plus (le bouton reprend le titre du moyen de paiement). Les remboursements totaux et partiels sont pris en charge en pesos entiers. Un montant partiel avec décimales est refusé avec Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. Le dernier reliquat d'un total de commande avec décimales est arrondi comme le débit. Le remboursement est envoyé dans l'environnement où le paiement a été effectué ; en production, les identifiants de production doivent donc être renseignés.

Transbank répond par une annulation de type REVERSED ou NULLIFIED. Un remboursement réussi est ajouté aux notes de commande avec le montant, le type, le code d'autorisation et le solde restant chez Transbank. Si Transbank n'accepte pas le remboursement, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Les remboursements effectués dans le portail Transbank ne sont pas importés dans 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 WooCommerce > Settings > Payments > Transbank Webpay Plus. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, et votre domaine. Utilisez Check now pour vérifier à nouveau le statut, Change key pour saisir 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 seul domaine. Retirer 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, Webpay Plus 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. Les gestionnaires de la boutique connectés voient toujours le moyen de paiement, marqué (unlicensed — visible to admins only), afin de pouvoir configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. 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, l'extension continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Webpay Plus n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable / Disable est activé, que la devise de la boutique est CLP (sur la page Pay for order, la devise de la commande) et, lorsque le mode d'intégration est désactivé, qu'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.

Le paiement a abouti, mais la commande reste Pending payment : Transbank n'a pas de webhook ; la commande n'est donc confirmé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. Vérifiez les notes de commande et le journal, ainsi que 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é. La commande n'a pas été modifiée et une note a été ajoutée. Le client peut réessayer dans un instant. Si le portail Transbank affiche la transaction comme autorisée, confirmez-la là-bas avant l'expédition.

Le client voit une erreur lors de la passation de la commande : activez Debug log et consultez WooCommerce > Status > Logs, source wcp_transbank_gateway. 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. Une commande dans une autre devise que CLP ne peut pas être payée avec Webpay.

Les totaux et les remboursements diffèrent de quelques pesos : les prix en CLP comportent des décimales. Webpay débite des pesos entiers, les totaux sont donc arrondis. Réglez Number of decimals sur 0.

Le remboursement échoue avec The production Commerce Code / API Key are missing : le paiement a été effectué 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 le motif ou le type et le code de réponse renvoyés. Aucun montant n'a été remboursé. Vérifiez la transaction dans le portail Transbank.

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é pour le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.

Désinstallation

La désactivation de l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension sont toujours supprimés. Les réglages de la passerelle, les autres options et les données temporaires de l'extension, ainsi que ses journaux (fichiers de log, y compris ceux archivés, et entrées de journal en base de données), ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les données Transbank enregistrées sur les commandes sont toujours conservées, car elles sont nécessaires à la comptabilité et aux remboursements. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

Transbank et Webpay sont des marques de leur titulaire respectif. Cette extension n'est ni affiliée à Transbank ni approuvée par Transbank.