VibeFox Tranzila for WooCommerce — Aide

Prérequis

WordPress : 6.0 ou ultérieur.

WooCommerce : 8.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Devise de la boutique : ILS, USD, EUR ou GBP. Pour les autres devises, le mode de paiement est masqué au moment du paiement.

Terminal Tranzila : vous avez besoin du nom du terminal. Le mot de passe du terminal (TranzilaPW) est nécessaire pour le handshake et pour les remboursements depuis WooCommerce. Certains terminaux exigent aussi un mot de passe crédit distinct (CreditPass) pour les remboursements. Le nom du terminal et les mots de passe sont fournis par Tranzila : consultez les paramètres de votre terminal ou demandez-les au support Tranzila. Tranzila ne propose pas de sandbox public. Pour les tests, Tranzila vous fournit un terminal de test distinct ; saisissez son nom comme nom de terminal.

IP réelle du visiteur : les notifications de paiement sont vérifiées par rapport à l'adresse IP du serveur Tranzila. Si votre site se trouve derrière un proxy ou un CDN tel que Cloudflare, le serveur web doit transmettre à PHP l'IP réelle du visiteur (REMOTE_ADDR).

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_tranzila_payment_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

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

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

5. Renseignez le Terminal name (supplier), et le Terminal password (TranzilaPW) si vous utilisez le handshake ou les remboursements.

6. Laissez Notifications activé et vérifiez Trusted IP : cette liste doit contenir les adresses IP depuis lesquelles Tranzila envoie les notifications. Faites confirmer la liste par le support Tranzila.

7. Recommandé : activez le handshake dans le terminal Tranzila, autorisez-y l'adresse IP de votre serveur, puis activez Handshake dans l'extension.

8. Activez Enable/Disable et testez un paiement avec le terminal de test Tranzila.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Tranzila. Au-dessus des champs, la page vous avertit lorsque le nom du terminal est vide (le mode de paiement est alors masqué au moment du paiement), lorsque les notifications sont désactivées ou que Trusted IP est vide (les commandes payées sont alors mises en attente pour examen manuel), lorsque le handshake est activé sans mot de passe de terminal (la page de paiement ne peut pas s'ouvrir) et lorsque la devise de la boutique n'est pas prise en charge. À l'enregistrement, un nom de terminal invalide ou une entrée invalide dans Trusted IP n'est pas enregistré : la page affiche une erreur et la valeur précédente est conservée. Les nombres hors de la plage autorisée sont ramenés à la valeur autorisée la plus proche.

General

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

Title : le nom du mode de paiement que les clients voient au moment du paiement. Par défaut : Credit Card (Tranzila).

Description : le texte affiché sous le mode de paiement au moment du paiement. Par défaut : Pay securely with your credit card on the Tranzila payment page.

Terminal

Terminal name (supplier) : le nom de votre terminal Tranzila, par exemple myshop. Lettres, chiffres, « - » et « _ » uniquement. Tant qu'il n'est pas saisi, le mode de paiement n'est pas affiché au moment du paiement. Pour les tests, saisissez le nom de votre terminal de test Tranzila.

Terminal password (TranzilaPW) : le mot de passe API du terminal. Il est nécessaire pour le handshake et pour les remboursements depuis WooCommerce.

Refund password (CreditPass) : uniquement si votre terminal exige un mot de passe distinct pour les transactions de crédit (remboursements). Laissez-le vide sinon.

Payment page

Payment page version : la page Tranzila affichée dans l'iframe.

Payment page language : la langue de la page Tranzila : Site language, Hebrew, English, Russian, Spanish, German, French ou Japanese. Par défaut : Hebrew. Site language utilise la langue de la locale WordPress du visiteur lorsqu'il s'agit de l'une de ces langues, sinon English.

iFrame width (px) : de 300 à 1200. Par défaut : 600. Sur les petits écrans, le cadre n'est jamais plus large que la page.

iFrame height (px) : de 400 à 1500. Par défaut : 650.

Max installments : le nombre maximal de paiements (tashlumim) que le client peut choisir sur la page de paiement, jusqu'à 36. 0 ou 1 signifie pas de paiement en plusieurs fois. Par défaut : 0. Le terminal doit être autorisé à traiter les paiements en plusieurs fois.

Handshake : Lock the amount with a handshake token (recommended). Avant d'ouvrir la page de paiement, la boutique demande à Tranzila un jeton unique lié au montant de la commande, afin que ce montant ne puisse pas être modifié dans le navigateur. Cela nécessite le mot de passe du terminal, le handshake activé dans le terminal Tranzila et l'autorisation de l'adresse IP de votre serveur dans ce terminal. Par défaut : désactivé.

Payment confirmation

Les notifications Tranzila ne sont pas signées. Une commande n'est marquée payée que lorsque la notification provient d'une Trusted IP et que sa clé de commande, son terminal, son montant et sa devise correspondent à la commande. Avec le handshake activé, le jeton doit également correspondre à la page de paiement de la commande. Le retour du client depuis la page de paiement ne marque jamais une commande comme payée.

Notifications : Confirm payments automatically with Tranzila notifications (notify URL). Par défaut : activé. L'URL de notification est envoyée à Tranzila avec chaque paiement, vous n'avez donc pas à la saisir dans le terminal Tranzila. Elle ressemble à https://your-site/wc-api/tranzila_p_callback/ et s'affiche sous le champ. Lorsque les notifications sont désactivées, un client qui revient d'une page de paiement réussie voit sa commande mise en attente, et vous confirmez le paiement manuellement après l'avoir vérifié dans le terminal Tranzila.

Trusted IP : les adresses IP ou plages CIDR des serveurs Tranzila qui envoient les notifications, séparées par des virgules. Par défaut : 80.244.170.7. Faites confirmer la liste actuelle par le support Tranzila. Les notifications provenant d'autres adresses sont rejetées. Si le champ est vide, les notifications ne peuvent pas être vérifiées : un paiement réussi signalé met la commande en attente d'examen manuel, et un refus signalé ne modifie pas la commande.

Advanced

Debug log : Log payment page, notification and refund events écrit dans WooCommerce > Status > Logs, source wcp_tranzila_payment_gateway. Les erreurs sont toujours journalisées, même si cette option est désactivée. Les mots de passe, jetons et données clients ne sont jamais écrits. Par défaut : désactivé.

Delete data on uninstall : Delete the settings, logs and Tranzila order data when the plugin is deleted. Par défaut : désactivé.

Paiement

Le client choisit le mode de paiement (par défaut Credit Card (Tranzila)) et clique sur Continue to payment. La commande est créée avec le statut En attente de paiement, et le client est dirigé vers la page de paiement de la commande de votre boutique. Il y voit la page de paiement Tranzila dans un iframe, avec le total de la commande dans la devise de la commande, les coordonnées de facturation et une courte liste des produits commandés. La page indique Enter your card details on the secure Tranzila payment page below. If it does not load, click "Proceed to payment". Le lien Choose another payment method se trouve sous le cadre. Si les paiements en plusieurs fois sont autorisés, le client en choisit le nombre sur la page Tranzila.

Après un paiement réussi, Tranzila renvoie le client et toute la fenêtre passe à la page de confirmation de commande de votre boutique. La commande n'est marquée payée qu'une fois que Tranzila la confirme par une notification. D'ici là, la page affiche Your payment is being confirmed by Tranzila. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Si la commande est mise en attente d'examen, elle affiche Your payment is being reviewed by the store. You will receive an e-mail once it is confirmed.

Si le paiement est refusé ou annulé, le client revient sur la page de paiement de la commande avec le message The payment was not completed. You have not been charged — please try again or choose another payment method. Lorsque Tranzila renvoie un code de réponse, le motif et le code sont ajoutés, par exemple que la carte est expirée. Le client peut payer à nouveau ou choisir un autre mode de paiement.

Si la page de paiement ne peut pas s'ouvrir, par exemple lorsque le handshake échoue, le client voit un bref message tel que Could not connect to Tranzila. Please try again in a moment. ainsi que le lien Choose another payment method. La raison technique est écrite dans le journal.

Le mode de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Sur la page Pay for order, il est proposé lorsque la devise de la commande est prise en charge. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).

L'extension ne prend que des paiements uniques par carte, sur la page Tranzila. Elle ne propose ni cartes ou jetons enregistrés, ni abonnements, ni autorisation et capture séparées (J5), ni boutons Bit, Apple Pay ou Google Pay propres (ce que propose votre page de paiement Tranzila s'affiche dans l'iframe), ni factures Tranzila.

Commandes et remboursements

Order statuses

Pending payment : le client a été envoyé sur la page de paiement et n'a pas encore payé, ou la notification Tranzila n'est pas encore arrivée.

Processing or Completed : le paiement a été confirmé par une notification vérifiée. WooCommerce définit Processing, ou Completed pour les commandes sans expédition. La note de commande indique le montant, la transaction Tranzila et le numéro d'autorisation, ainsi que le nombre de paiements s'il y en a. L'ID de transaction est l'index de transaction Tranzila.

On hold : le paiement a été reçu mais n'a pas été accepté automatiquement : le montant, la devise ou le jeton de handshake ne correspondait pas à la commande, la notification n'a pas pu être vérifiée parce que Trusted IP est vide, ou les notifications sont désactivées et le client est revenu d'une page de paiement réussie. La note de commande explique la raison. Vérifiez le paiement dans le terminal Tranzila et modifiez le statut manuellement.

Failed : Tranzila a signalé un paiement refusé pour une commande en attente. La note indique le code de réponse et sa signification. Une commande déjà payée ne passe jamais à Failed.

Si un paiement arrive pour une commande annulée, la commande est rouverte avec une note vous demandant de vérifier le stock avant l'expédition. Si le client a changé de mode de paiement sur la page Pay for order mais a payé sur une page Tranzila encore ouverte, le mode de paiement de la commande est remis sur Tranzila. Si un second paiement arrive pour une commande déjà payée, terminée ou remboursée, la commande n'est pas modifiée. Une note vous demande de la vérifier et de rembourser le doublon dans le terminal Tranzila. Les notifications répétées de la même transaction sont ignorées.

Refunds

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Credit Card (Tranzila) (le bouton affiche le titre du mode de paiement). Les remboursements totaux et partiels sont pris en charge. Le remboursement est effectué sous forme de transaction de crédit Tranzila sur le paiement d'origine. Le bouton est disponible lorsque le mot de passe du terminal est renseigné et que la commande a une transaction Tranzila confirmée avec un numéro d'autorisation. Un remboursement réussi est ajouté aux notes de commande avec la transaction de crédit Tranzila.

Si Tranzila n'accepte pas le remboursement, WooCommerce affiche l'erreur, par exemple Tranzila declined the refund avec le code, et aucun remboursement n'est enregistré. Une commande payée sur un autre terminal que celui des réglages actuels (par exemple un terminal de test) ne peut pas être remboursée depuis WooCommerce ; remboursez-la dans ce terminal Tranzila. Les remboursements effectués dans le terminal Tranzila ne sont pas signalés à la boutique. Si nécessaire, créez un remboursement manuel dans WooCommerce sans utiliser le bouton Tranzila.

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 > Tranzila. 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-le dans votre compte vibefox.net.

Sans clé active, Tranzila 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 connectés de la boutique voient toujours le mode de paiement, marqué (unlicensed — visible to admins only), afin que vous puissiez 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 le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Tranzila does not appear at checkout : vérifiez que la licence est active, que Enable/Disable est activé, que Terminal name (supplier) est renseigné et que la devise de la boutique (sur la page Pay for order, la devise de la commande) est ILS, USD, EUR ou GBP. La page des réglages affiche un avertissement lorsque le nom du terminal est absent ou que la devise n'est pas prise en charge.

The payment went through, but the order stays Pending payment : la notification n'est pas arrivée ou a été rejetée. Vérifiez que Notifications est activé et que Trusted IP contient les adresses depuis lesquelles Tranzila envoie les notifications. Les erreurs sont toujours écrites dans WooCommerce > Status > Logs, source wcp_tranzila_payment_gateway. Le message indiquant qu'une IP ne figure pas dans la liste Trusted IP signifie qu'il faut corriger le réglage Trusted IP ou la configuration de votre proxy : derrière un proxy ou un CDN, le serveur web doit transmettre à PHP l'IP réelle du visiteur.

Notification answers Forbidden : elle provient d'une adresse IP absente de Trusted IP.

Notification answers Bad request or Not found : la commande, sa clé de commande, le terminal ou l'index de transaction de la notification ne correspondent à aucune commande de cette boutique.

Notification answers Accepted for manual review : Trusted IP est vide, la notification n'a donc pas pu être vérifiée. Un paiement réussi met la commande en attente. Renseignez Trusted IP pour confirmer les paiements automatiquement.

Notification answers Busy, retry : la commande était traitée par une autre requête au même moment, et la notification n'a pas été appliquée. Vérifiez le paiement dans le terminal Tranzila ; si la commande attend toujours le paiement et que celui-ci est approuvé là-bas, modifiez le statut manuellement.

Some paid orders are On hold : lisez la note de commande. Le montant, la devise ou le jeton de handshake ne correspondaient pas, ou la notification n'a pas pu être vérifiée (Trusted IP vide, ou notifications désactivées). Vérifiez le paiement dans le terminal Tranzila et modifiez le statut manuellement.

The payment page does not open with the handshake on : vérifiez le nom et le mot de passe du terminal, que le handshake est activé dans le terminal Tranzila et que l'adresse IP de votre serveur y est autorisée. Le journal indique la raison.

Refunds fail : les remboursements nécessitent le Terminal password (TranzilaPW). Certains terminaux exigent aussi un mot de passe crédit distinct ; saisissez-le dans Refund password (CreditPass). Les commandes payées sur un autre terminal doivent être remboursées dans ce terminal.

Other currencies : l'extension prend en charge ILS, USD, EUR et GBP. Les développeurs peuvent modifier cette liste avec le filtre tranzila_p_currency_map.

The license block shows an error : 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 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 données Tranzila enregistrées sur les commandes et les journaux de l'extension (y compris les fichiers de journal archivés) ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

Tranzila est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à Tranzila ni approuvée par Tranzila.