VibeFox Tranzila 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 plus anciennes de PHP.

Devise de la boutique : ILS, USD, EUR ou GBP. Pour les autres devises du panier, le mode de paiement est masqué à l'étape de 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 la page de commande. Certains terminaux exigent aussi un mot de passe de 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 bac à sable public. Pour les tests, Tranzila vous fournit un terminal de test distinct ; saisissez son nom comme nom du terminal.

IP réelle du visiteur : les notifications de paiement sont vérifiées à partir de l'adresse IP du serveur Tranzila. Si votre boutique 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 le back office, allez dans Modules > Module Manager et cliquez sur Upload a module. Sélectionnez le fichier ZIP du module.

2. Une fois le téléversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Tranzila Payment 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. Saisissez le Terminal name (supplier), et le Terminal password (TranzilaPW) si vous utilisez le handshake ou les remboursements.

5. Laissez Notifications activé et vérifiez Trusted IP : ce champ doit contenir les adresses IP depuis lesquelles Tranzila envoie les notifications. Confirmez la liste auprès du support Tranzila.

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

7. Activez Enable/Disable, cliquez sur Save et testez un paiement avec le terminal de test Tranzila.

À l'installation, le module crée le statut de commande Tranzila payment on hold. PrestaShop propose à un nouveau module de paiement toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les limiter dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Tranzila Payment Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit lorsque le nom du terminal est vide (le mode de paiement est alors masqué à l'étape de paiement), lorsque les notifications sont désactivées ou que Trusted IP est vide (les commandes payées sont alors mises en attente de vérification manuelle), lorsque le handshake est activé sans mot de passe de terminal (la page de paiement ne peut pas être ouverte) et lorsque la devise par défaut de la boutique n'est pas prise en charge. Lors de l'enregistrement, un nom de terminal invalide, une entrée invalide dans Trusted IP ou un champ numérique qui n'est pas un nombre entier n'est pas enregistré : la page affiche une erreur et l'ancienne valeur est conservée. Un nombre hors de la plage autorisée est enregistré à la valeur autorisée la plus proche, et la page vous en informe.

Tranzila

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 voient les clients à l'étape de paiement, et le titre de la page de paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Credit Card (Tranzila).

Description : le texte affiché sous le mode de paiement à l'étape de 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é à l'étape de paiement. Pour les tests, saisissez le nom de votre terminal de test Tranzila.

Terminal password (TranzilaPW) : le mot de passe API du terminal. Nécessaire pour le handshake et pour les remboursements depuis la page de commande.

Refund password (CreditPass) : seulement si votre terminal exige un mot de passe distinct pour les transactions de crédit (remboursements). Sinon, laissez-le vide.

Les mots de passe 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 passwords : cochez un mot de passe et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

Page de paiement

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

Payment page language : la langue de la page Tranzila : Site language, hébreu, anglais, russe, espagnol, allemand, français ou japonais. Par défaut : hébreu. Site language utilise la langue du panier du client lorsqu'il s'agit de l'une de ces langues, sinon l'anglais.

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 en plusieurs fois (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 : verrouille le montant avec un jeton de handshake (recommandé). Avant d'ouvrir la page de paiement, la boutique demande à Tranzila un jeton unique lié au montant, afin que celui-ci 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'IP de votre serveur dans ce terminal. Par défaut : désactivé.

Confirmation du paiement

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

Notifications : confirme automatiquement les paiements grâce aux notifications Tranzila (URL de notification). Par défaut : activé. Lorsque les notifications sont désactivées, un client qui revient d'une page de paiement réussie crée la commande au statut Tranzila payment on hold, et vous confirmez le paiement manuellement après avoir vérifié le terminal Tranzila.

Notification URL : affichée à titre informatif. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_tranzila_payment_gateway/notify, éventuellement avec un code de langue. L'URL est envoyée à Tranzila à chaque paiement : vous n'avez donc pas à la saisir 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. Confirmez la liste actuelle auprès du 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é crée la commande au statut Tranzila payment on hold pour vérification manuelle, et un refus signalé ne modifie rien.

Avancé

Debug log : consigne les événements de la page de paiement, des notifications et des remboursements dans logs/tranzila_p_debug.log.php, dans le dossier du module. Ce fichier ne peut pas être ouvert depuis le web. Les avertissements et erreurs sont toujours consignés, même lorsque cette option est désactivée. Les mots de passe, jetons et données clients ne sont jamais écrits. 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 : lorsqu'elle est activée, la désinstallation du module supprime les réglages et les journaux. Les transactions et remboursements Tranzila ainsi que le statut de commande Tranzila payment on hold sont toujours conservés, car les anciennes commandes en ont besoin. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le mode de paiement (par défaut Credit Card (Tranzila)) et voit la description ainsi que la note After you confirm, you will enter your card details on the secure Tranzila payment page. The order is created once Tranzila confirms the payment. Après confirmation, le client est redirigé vers une page de paiement de votre boutique. Il y voit la page de paiement Tranzila dans un iframe, avec le total du panier dans la devise du panier, les coordonnées de facturation et une courte liste des produits. 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 choisit leur nombre sur la page Tranzila. Aucune commande n'existe encore à ce stade.

Après un paiement réussi, Tranzila renvoie le client et toute la fenêtre passe à l'étape suivante. La commande n'est marquée payée qu'une fois que Tranzila l'a confirmé par une notification. Si la notification est déjà arrivée, le client voit la page standard de confirmation de commande avec Your payment with Tranzila has been received. Si la commande est en attente de vérification, la page affiche Your payment is being reviewed by the store. You will receive an e-mail once it is confirmed. Si la notification n'est pas encore arrivée, une page Payment confirmation 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. ainsi qu'un bouton Check again.

Si le paiement est refusé ou annulé, le client revient à l'étape de paiement 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, la raison et le code sont ajoutés, par exemple que la carte a expiré. Le panier est conservé et aucune commande n'est créée. Chaque ouverture de la page de paiement crée une nouvelle page de paiement avec son propre jeton.

Si la page de paiement ne peut pas être ouverte, 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. et le bouton Choose another payment method. La raison technique est consignée dans le journal.

La notification fonctionne pendant que la boutique est en mode maintenance et n'est pas bloquée par la restriction géographique de votre boutique. La même page de paiement est utilisée avec les thèmes Classic et Hummingbird.

Le module ne prend en charge que les paiements uniques par carte, sur la page Tranzila. Il ne gère 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

Statuts de commande

No order yet : le client a été envoyé vers la page de paiement et n'a pas payé, le paiement a été refusé, ou la notification Tranzila n'est pas encore arrivée. Seul le panier existe.

Payment accepted : le paiement a été confirmé par une notification vérifiée. Le paiement est enregistré avec l'index de transaction Tranzila comme ID de transaction, et une note indique le montant, la transaction, le numéro d'autorisation et le nombre de paiements en plusieurs fois, s'il y en a.

Tranzila payment on hold : le paiement a été signalé mais pas accepté automatiquement : le montant, la devise ou le jeton de handshake ne correspondaient pas, 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 explique la raison. Vérifiez le paiement dans le terminal Tranzila et modifiez le statut manuellement.

Refunded : le paiement a été entièrement remboursé via le module.

Si un paiement arrive pour une commande annulée, celle-ci repasse au statut Payment accepted, avec une note vous demandant de vérifier le stock avant l'expédition. Si un second paiement arrive pour une commande déjà payé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 d'une même transaction sont ignorées.

Bloc de paiement Tranzila

La page de commande affiche un bloc Tranzila payment avec l'index de transaction, le numéro d'autorisation, le terminal, le statut, le montant payé et remboursé, le nombre de paiements en plusieurs fois, l'historique des remboursements, toutes les Payment pages of the cart avec leur résultat, ainsi que les Tranzila notes de la commande.

Remboursements

Dans le bloc Tranzila payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Tranzila. Confirmez la question Refund this amount via Tranzila? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez avoir le droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. Le remboursement est effectué sous forme de transaction de crédit Tranzila du paiement d'origine, sur le terminal qui l'a encaissé, pour le montant et la devise que Tranzila a effectivement débités. Ainsi, après un écart de montant ou de devise, vous pouvez rembourser jusqu'au montant que le client a réellement payé, et non le total de la commande.

Le formulaire est disponible lorsque le mot de passe du terminal est défini et que la commande a une transaction Tranzila confirmée avec un numéro d'autorisation. Sinon, le bloc indique pourquoi, par exemple Refunds need the terminal password (TranzilaPW) in the gateway settings. 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 la page de commande ; remboursez-la dans ce terminal Tranzila.

Si Tranzila n'accepte pas le remboursement, le bloc affiche l'erreur, par exemple Tranzila declined the refund avec le code et sa signification, et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec la transaction de crédit Tranzila. Un remboursement total place la commande au statut Refunded. Un remboursement partiel ne modifie pas le statut.

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 Tranzila. Les remboursements effectués dans le terminal Tranzila ne sont pas signalés à la boutique. Mettez la commande à jour manuellement si nécessaire.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Tranzila Payment Gateway est le premier bloc de Modules > Module Manager > VibeFox Tranzila Payment 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-tranzila 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, Tranzila n'est pas affiché aux clients à l'étape 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 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 à l'étape de 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 par la notification Tranzila et le retour vers la boutique, et les remboursements 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

Tranzila n'apparaît pas à l'étape de paiement : vérifiez que la licence est active, que Enable/Disable est activé, que Terminal name (supplier) est renseigné et que la devise du panier 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 par défaut n'est pas prise en charge. 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 paiement a abouti, mais aucune commande n'a été créée : 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 le journal ; consultez le champ Log sur la page du module. 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. Les développeurs dont la boutique se trouve derrière un reverse proxy de confiance peuvent définir l'IP avec le hook actionTranzilaPRemoteIp.

La notification répond Forbidden : elle provient d'une adresse IP absente de Trusted IP.

La notification répond Bad request ou Not found : le panier, le jeton de la page de paiement, le terminal ou l'index de transaction de la notification ne correspondent à aucune page de paiement de cette boutique.

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

La notification répond Busy, retry : le panier était en cours de traitement par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple, le module est désactivé). Le journal indique la raison. Vérifiez le paiement dans le terminal Tranzila ; s'il y est approuvé et qu'aucune commande n'a été créée, contactez le client ou créez la commande manuellement.

Certaines commandes sont en Tranzila payment on hold : lisez les notes du bloc Tranzila payment. 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.

La page de paiement ne s'ouvre pas avec le handshake activé : vérifiez le nom du terminal et le mot de passe du terminal, que le handshake est activé dans le terminal Tranzila et que l'IP de votre serveur y est autorisée. Le journal indique la raison.

Les remboursements échouent : les remboursements nécessitent le Terminal password (TranzilaPW). Certains terminaux exigent aussi un mot de passe de crédit distinct ; saisissez-le dans Refund password (CreditPass). Les commandes payées sur un autre terminal doivent être remboursées dans ce terminal. Si la réponse de Tranzila est inattendue, le bloc indique que le remboursement n'a pas été confirmé : vérifiez le terminal Tranzila avant de réessayer.

Autres devises : le module ne prend en charge que ILS, USD, EUR et GBP.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Tranzila Payment 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 et les journaux 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 Tranzila ainsi que le statut de commande Tranzila payment on hold sont toujours conservés, afin que les commandes payées auparavant puissent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

Tranzila est une marque de son propriétaire respectif. Ce module n'est ni affilié à Tranzila ni approuvé par Tranzila.