VibeFox Datatrans for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les anciennes versions de PHP.

Compte Datatrans : vous avez besoin du Merchant ID, du mot de passe d'API serveur à serveur et, de préférence, de la clé de signature HMAC-SHA256 pour les webhooks. Les identifiants sandbox proviennent du Web Admin sandbox de Datatrans (admin.sandbox.datatrans.com), les identifiants de production du Web Admin de production (admin.datatrans.com). Sandbox et production sont des comptes Datatrans distincts, avec des Merchant ID et des clés différents.

Boutique accessible : Datatrans envoie les webhooks depuis ses propres serveurs ; votre boutique doit donc être accessible depuis Internet.

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 Datatrans Gateway dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key du bloc de licence en haut de la page Configure et cliquez sur Activate (voir Clé de licence).

4. Saisissez les identifiants sandbox du Web Admin sandbox de Datatrans (voir Configuration).

5. Activez Enable/Disable et cliquez sur Save. Effectuez un paiement test en mode sandbox. Lorsque tout fonctionne, saisissez les identifiants de production et désactivez Sandbox mode.

À l'installation, le module crée le statut de commande Datatrans payment on hold. PrestaShop active par défaut 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 ; Datatrans n'est affiché que pour les devises autorisées à cet endroit.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Datatrans Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Lorsque le mode de paiement est activé mais que l'environnement actuel n'a pas de Merchant ID ou de mot de passe d'API, la page affiche Datatrans is hidden at checkout until these settings are filled in: avec les champs manquants. Tant que le mode sandbox est activé, la page affiche Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged.

Datatrans

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

Title : le nom du mode de paiement que le client voit au moment du paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Datatrans. Obligatoire.

Description : le texte affiché sous le mode de paiement au moment du paiement. Par défaut : Pay securely via Datatrans.

Sandbox mode : utilise la sandbox Datatrans : paiements test, aucun argent réel. Ce commutateur change à la fois les serveurs Datatrans et les identifiants utilisés pour les nouveaux paiements. Par défaut : activé. Désactivez-le pour encaisser de vrais paiements. Tant qu'il est activé, le client voit Sandbox mode: no real payment is taken. sous le mode de paiement. Les remboursements et les captures utilisent toujours l'environnement dans lequel le paiement a été effectué, quelle que soit la position de ce commutateur.

Identifiants sandbox

Copiez-les depuis le Web Admin sandbox de Datatrans (admin.sandbox.datatrans.com). La clé de signature s'y trouve, dans les paramètres de sécurité.

Sandbox merchant ID : le Merchant ID de votre compte sandbox.

Sandbox API password : le mot de passe d'API serveur à serveur du compte sandbox.

Sandbox HMAC sign key : la clé hexadécimale utilisée pour vérifier l'en-tête Datatrans-Signature des webhooks. Sans elle, chaque webhook est vérifié à nouveau auprès de l'API de statut de Datatrans.

Identifiants de production

Copiez-les depuis le Web Admin de production de Datatrans (admin.datatrans.com).

Production merchant ID : le Merchant ID de votre compte de production.

Production API password : le mot de passe d'API serveur à serveur du compte de production.

Production HMAC sign key : la clé hexadécimale utilisée pour vérifier l'en-tête Datatrans-Signature des webhooks de production. Sans elle, chaque webhook est vérifié à nouveau auprès de l'API de statut de Datatrans.

Les mots de passe et clés de signature enregistrés ne sont jamais réaffichés. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier. Une clé de signature doit être une chaîne hexadécimale telle que délivrée par Datatrans. Toute autre valeur n'est pas enregistrée : la page affiche une erreur et conserve la valeur précédente, les autres réglages sont enregistrés.

Clear saved secrets : cochez un mot de passe ou une clé de signature et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

URL du webhook

Cette section affiche l'URL du webhook de votre boutique. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_datatrans_gateway/webhook, éventuellement avec un code de langue comme /en/. Le module transmet cette URL à Datatrans pour chaque transaction, vous n'avez donc rien à saisir. Vous pouvez aussi la saisir dans les paramètres de webhook du Web Admin de Datatrans pour recevoir les mises à jour des captures et annulations effectuées là-bas ; copiez-la exactement comme l'affichent les paramètres. Les remboursements effectués dans le Web Admin de Datatrans ne sont pas reflétés dans la commande.

Le webhook indique l'état de la transaction. Le module réagit à ces états :

Avec une clé de signature HMAC, chaque webhook est vérifié grâce à son en-tête Datatrans-Signature, avec la clé de signature de l'environnement dans lequel le paiement a été effectué. Les webhooks sans signature valide sont rejetés. Sans clé de signature, le module ne fait pas confiance au contenu du webhook et vérifie chaque webhook auprès de l'API de statut de Datatrans. Sans webhook, une commande n'est créée que lorsque le client revient dans la boutique après avoir payé.

Traitement du paiement

Auto settle : capture (règle) les paiements immédiatement. Si désactivé, les paiements sont seulement autorisés : la commande passe en Datatrans payment on hold et vous la capturez plus tard avec Capture Datatrans payment dans le bloc Datatrans de la commande, ou vous la libérez avec Cancel Datatrans authorization. Par défaut : activé.

Order status after payment : le statut de la commande une fois le paiement réglé.

Les paiements uniquement autorisés et les écarts de montant ou de devise vont toujours en Datatrans payment on hold.

Avancé

Logging : enregistre les événements de paiement et les appels API dans logs/datatrans_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours journalisées, même lorsque ce commutateur est désactivé. Aucune clé, donnée de carte ni donnée client n'est écrite. Par défaut : désactivé.

Log : affiche la taille et les dernières entrées du journal, avec un bouton pour le vider.

Delete data on uninstall : lorsque l'option est activée, la désinstallation du module supprime ses réglages et le journal. Les enregistrements de paiement Datatrans des commandes (transactions, remboursements) et le statut de commande restent toujours. Par défaut : désactivé.

Tunnel de commande

À l'étape de paiement, le client choisit le mode de paiement (par défaut Datatrans) et voit la mention You will be redirected to the Datatrans payment page to complete the payment securely. Après confirmation, le module crée une transaction Datatrans pour le total du panier dans la devise du panier et envoie le client vers la page de paiement Datatrans. La page s'affiche en allemand, en anglais, en français ou en italien si la langue de la boutique est l'une de celles-ci. Le client y paie avec n'importe quel mode activé dans votre compte Datatrans. À ce stade, aucune commande n'existe encore.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée payée qu'après confirmation de Datatrans : par le webhook ou par une requête serveur à l'API de statut de Datatrans lorsque le client revient. L'adresse de retour contient la clé sécurisée du panier, et le retour lui-même ne crée jamais de commande. La commande est ensuite créée et le client voit la page standard de confirmation de commande avec Your payment with Datatrans has been received. Pour un paiement uniquement autorisé, la page affiche Your payment with Datatrans has been authorized. The amount will be charged when your order is processed. Si Datatrans n'a pas encore confirmé le paiement, une page Payment confirmation affiche Your payment is being confirmed by Datatrans. You will receive an e-mail as soon as it is confirmed. Please do not pay again. avec un bouton Check again ; le webhook crée la commande dès son arrivée.

Si le client annule sur la page Datatrans, il revient au tunnel de commande avec The payment was canceled. You can try again or choose another payment method. Si le paiement a échoué, le message est The payment was not completed. Please try again or choose another payment method. Le panier est conservé. Une nouvelle tentative crée une nouvelle transaction Datatrans ; un paiement tardif d'une tentative précédente est toujours reconnu.

Si Datatrans ne peut pas démarrer le paiement, le client reste au tunnel de commande avec The payment could not be started. Please try again or choose another payment method. La raison technique est écrite dans le journal.

Le webhook fonctionne lorsque la boutique est en mode maintenance et n'est pas bloqué par la restriction géographique de votre boutique.

Le module gère les paiements uniques sur la page de paiement Datatrans. Il ne gère ni cartes enregistrées ou alias, ni abonnements, ni Lightbox ou Secure Fields sur votre site, ni choix des méthodes de paiement dans les réglages, ni capture partielle d'une autorisation.

Commandes et remboursements

Statuts de commande

Pas encore de commande : le client a été envoyé vers Datatrans et n'a pas payé, le paiement a échoué ou a été annulé, ou Datatrans ne l'a pas encore confirmé. Seul le panier existe.

Payment accepted, Delivered ou Datatrans payment on hold : le paiement a été réglé. Le statut suit Order status after payment. Le paiement est enregistré avec l'ID de transaction Datatrans, et une note indique le montant, le mode de paiement, l'environnement et la manière dont il a été confirmé (webhook ou retour).

Datatrans payment on hold après une autorisation : Auto settle est désactivé et le paiement est seulement autorisé. Capturez-le ou annulez-le dans le bloc de la commande.

Datatrans payment on hold après le paiement : Datatrans a signalé un montant ou une devise différent du total du panier (par exemple, le panier a été modifié après le début du paiement), ou le paiement est arrivé après l'annulation de la commande. La note l'explique. Vérifiez la transaction dans le Web Admin de Datatrans, puis traitez la commande ou remboursez le paiement.

Canceled : l'autorisation a été libérée, dans le bloc de la commande ou dans le Web Admin de Datatrans.

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

Si un second paiement arrive pour un panier déjà payé ou autorisé, la commande ne change pas. Une note vous demande de le vérifier et de rembourser le doublon dans Datatrans. Une transaction échouée ou annulée ne rétrograde jamais une commande payée.

Bloc Datatrans payment

La page de commande affiche un bloc Datatrans payment avec l'ID de transaction, le statut Datatrans, le mode de paiement, le montant, les montants payés et remboursés, un badge Sandbox pour les paiements sandbox, l'historique des remboursements et les Datatrans notes de la commande. Les actions du bloc nécessitent le droit de modifier les commandes ; l'accès aux pages des modules n'est pas nécessaire.

Capturer et annuler

Pour un paiement uniquement autorisé, le bloc affiche Capture Datatrans payment et Cancel Datatrans authorization. La capture règle le paiement pour le total actuel de la commande, qui ne doit pas dépasser le montant autorisé ; la commande passe alors au statut de Order status after payment. L'annulation libère l'autorisation et place la commande en Canceled. Les deux actions visent l'environnement du paiement. Si Datatrans refuse, le bloc affiche l'erreur et une note est ajoutée.

Remboursements

Dans le bloc Datatrans payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Datatrans. Confirmez la question Refund this amount through Datatrans? This cannot be undone. Les remboursements totaux et partiels sont pris en charge, jusqu'au montant effectivement débité par Datatrans, déduction faite des remboursements précédents. Le remboursement est envoyé à l'environnement du paiement : le Merchant ID et le mot de passe d'API de cet environnement doivent donc être renseignés. Un remboursement relancé n'est pas crédité deux fois. Si Datatrans n'accepte pas le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique et aux notes avec l'ID de transaction de remboursement Datatrans. Un remboursement total passe la commande en Refunded ; un remboursement partiel ne modifie pas le statut.

Pour un paiement uniquement autorisé, rien n'a encore été débité : seul le montant total peut être « remboursé », ce qui annule l'autorisation. Les remboursements sont disponibles une fois que Datatrans a réglé le paiement ; une autorisation dont le montant ne correspond pas ne peut pas être remboursée tant qu'elle n'est pas réglée.

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 Datatrans. Les remboursements effectués dans le Web Admin de Datatrans ne sont pas enregistré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 Datatrans Gateway est le premier bloc de Modules > Module Manager > VibeFox Datatrans Gateway > Configure, au-dessus des réglages. Collez la clé dans License key et 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) et 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. En dessous figurent la ligne Product: presta-payment-datatrans 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, Datatrans 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. La vitrine de 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 moment du paiement. Un rappel apparaît dans Modules > Module Manager, dans l'onglet Alerts. 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, le module continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement pendant votre travail dans le back-office : une fois par jour pendant les 14 premiers jours suivant 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 licence.

Dépannage

Datatrans does not appear at checkout : vérifiez que la licence est active, que Enable/Disable est activé et que l'environnement actuel dispose de son Merchant ID et de son mot de passe d'API : les champs sandbox en mode sandbox, les champs de production sinon. La page des réglages liste les champs manquants. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client.

The payment went through, but no order was created : Datatrans n'a pas pu atteindre l'URL du webhook et le client n'est pas revenu dans la boutique. Vérifiez que la boutique est accessible depuis Internet et qu'aucun pare-feu ne bloque les requêtes vers l'URL du webhook. Vérifiez que la clé de signature des réglages appartient à l'environnement du paiement. Consultez le champ Log sur la page du module.

Webhook answers Invalid signature : la clé de signature HMAC des réglages ne correspond pas à celle du Web Admin de Datatrans, ou appartient à l'autre environnement. Copiez à nouveau la clé.

Webhook answers Not configured or Verification failed : le webhook devait être vérifié auprès de l'API de statut de Datatrans, mais les identifiants de cet environnement sont absents, ou Datatrans n'a pas répondu. Datatrans relance le webhook.

Webhook answers Busy, retry : la commande était en cours de confirmation par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple, parce que le module est désactivé). Datatrans relance le webhook. Le journal indique la raison.

The webhook URL shows Method not allowed in the browser : c'est normal. L'URL n'accepte que les requêtes de Datatrans.

The HMAC sign key is not saved : la clé doit être une chaîne hexadécimale. Copiez-la à nouveau depuis le Web Admin de Datatrans.

The customer sees Datatrans payments are not configured yet : le Merchant ID ou le mot de passe d'API de l'environnement actuel est absent.

The customer sees The payment could not be started : consultez le champ Log. Un Merchant ID ou un mot de passe d'API erroné, ou des identifiants d'un mauvais environnement, sont les causes habituelles.

Order is Datatrans payment on hold after payment : lisez les Datatrans notes dans le bloc de la commande (voir Statuts de commande), puis traitez la commande ou remboursez le paiement.

Capture is refused : le total de la commande est supérieur au montant autorisé. Datatrans ne peut pas régler plus que ce qui a été autorisé.

Refund or capture fails with a message about missing credentials : le paiement a été effectué dans l'autre environnement, et son Merchant ID ou son mot de passe d'API n'est pas renseigné. Saisissez-les et réessayez.

Désinstallation

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

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