VibeFox Datatrans for WooCommerce — Aide

Prérequis

WordPress: 6.0 ou ultérieur.

WooCommerce: 7.0 ou ultérieur, installé et activé.

PHP: 8.0 ou ultérieur.

HTTPS: votre site doit être accessible depuis internet en HTTPS afin que Datatrans puisse envoyer les webhooks.

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.

Devise : la devise de la boutique (ou la devise de commande de votre extension multidevise) doit être activée pour votre compte marchand Datatrans.

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 téléverser le dossier wcp_datatrans_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate. WooCommerce doit être activé.

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

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

5. Saisissez les identifiants sandbox et, pour les paiements réels, les identifiants de production (voir Configuration).

6. Activez Enable/Disable. Laissez Sandbox mode activé pendant vos tests, puis décochez-le pour accepter des paiements réels.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Datatrans. Lorsque la passerelle est activée mais que le Merchant ID ou le mot de passe d'API de l'environnement actuel est manquant, la page affiche Datatrans is hidden at checkout until these settings are filled in: avec la liste des champs manquants. Tant que le mode sandbox est activé, elle affiche Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged.

Webhook

La Webhook URL est affichée en haut des réglages. Elle ressemble à https://your-site/wc-api/datatrans_payment_callback/. L'extension envoie cette URL à Datatrans avec chaque transaction, vous n'avez donc pas à la saisir ailleurs. Vous pouvez aussi la saisir dans les réglages de webhook du Web Admin de Datatrans pour recevoir les mises à jour des captures et des annulations effectuées là-bas.

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

Avec une clé de signature HMAC, chaque webhook est vérifié grâce à son en-tête Datatrans-Signature. Les webhooks sans signature valide sont rejetés. Sans clé de signature, l'extension ne se fie pas au contenu du webhook et vérifie chaque webhook auprès de l'API de statut de Datatrans. Sans le webhook, une commande n'est confirmée que lorsque le client revient sur la boutique après avoir payé.

Général

Enable/Disable: Enable Datatrans Payment active ou désactive la méthode de paiement. Par défaut : désactivé.

Title: le nom de la méthode de paiement que les clients voient lors du paiement. Par défaut : Datatrans.

Description: le texte affiché sous la méthode de paiement lors du paiement. Par défaut : Pay securely via Datatrans.

Sandbox mode: Use the Datatrans sandbox (test payments, no real money). Il bascule à la fois les hôtes de l'API et de la page de paiement et les identifiants ci-dessous. Les remboursements et les captures utilisent toujours l'environnement dans lequel le paiement a été effectué. Par défaut : activé. Décochez-le pour accepter des paiements réels.

Identifiants sandbox

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

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

Sandbox API password: le mot de passe d'API serveur à serveur de votre 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 revérifié 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 de votre 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 revérifié auprès de l'API de statut de Datatrans.

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. Si vous mettez à jour depuis la version 1.0, l'unique jeu d'identifiants de cette version est déplacé vers les champs sandbox lorsque le mode sandbox était activé ; sinon, il reste dans les champs de production.

Traitement du paiement

Auto settle: Capture (settle) payments immediately. Par défaut : activé. Si vous le désactivez, les paiements sont seulement autorisés : la commande est mise en attente et vous la capturez plus tard avec l'action de commande Capture Datatrans payment, ou vous la libérez avec Cancel Datatrans authorization.

Order status after payment: le statut de commande défini une fois le paiement réglé. Le statut est défini immédiatement, sans second changement de statut.

Avancé

Logging: Log payment events and API calls écrit des détails dans WooCommerce > Status > Logs, source wcp_datatrans_gateway. Les erreurs sont toujours consignées. Aucune clé, aucune donnée de carte ni aucune donnée client n'est écrite. Par défaut : désactivé.

Delete data on uninstall: Remove the plugin settings when the plugin is deleted. Par défaut : désactivé.

Paiement

Le client choisit la méthode de paiement (par défaut Datatrans) et valide la commande. L'extension crée une transaction Datatrans pour le total de la commande dans la devise de la commande, avec l'ID de la commande comme référence, et envoie le client vers la page de paiement Datatrans. Le client y paie avec n'importe quelle méthode activée dans votre compte Datatrans, par exemple une carte, TWINT ou PostFinance. La page de paiement s'ouvre en allemand, anglais, français ou italien lorsque votre site utilise l'une de ces langues ; sinon, Datatrans choisit la langue.

Après le paiement, le client revient sur la page de commande reçue de votre boutique. La commande n'est marquée payée qu'une fois que Datatrans l'a confirmée : par le webhook ou par une requête côté serveur à l'API de statut de Datatrans lorsque le client revient. L'adresse de retour contient la clé de la commande, et le retour en lui-même ne marque jamais une commande comme payée.

Si le client annule sur la page de paiement, il est envoyé vers la page Pay for order avec le message The payment was canceled. You can try again or choose another payment method. Après un paiement échoué, le message est The payment was not completed. Please try again or choose another payment method. La commande reste payable et le client peut réessayer.

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

La méthode de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Elle est compatible avec le stockage des commandes haute performance (HPOS) de WooCommerce.

L'extension ne prend que les paiements uniques sur la page de paiement Datatrans. Elle ne gère ni cartes enregistrées ou alias, ni abonnements, ni intégration Lightbox ou Secure Fields, ni choix des méthodes de paiement dans les réglages, ni capture partielle d'une autorisation.

Commandes et remboursements

Statuts de commande

Pending payment: le client a été envoyé vers Datatrans et n'a pas encore payé, a annulé sur la page de paiement, ou Datatrans n'a pas encore confirmé le paiement. Chaque nouvelle transaction est consignée dans la commande avec son ID et son environnement.

Processing, Completed or On Hold: le paiement a été réglé. Le statut suit Order status after payment. La note de commande indique le montant, la méthode de paiement, l'ID de transaction Datatrans et l'environnement (sandbox ou production). L'ID de transaction est enregistré dans la commande.

On hold, authorized: avec Auto settle désactivé, le paiement a été autorisé mais pas capturé. Ouvrez la commande et choisissez Capture Datatrans payment ou Cancel Datatrans authorization dans les actions de commande. La capture utilise le total actuel de la commande, qui ne doit pas dépasser le montant autorisé. Si c'est le cas, ou si Datatrans refuse la capture ou l'annulation, la raison est ajoutée aux notes de la commande.

On hold after payment: Datatrans a indiqué un montant ou une devise différents du total de la commande (par exemple, la commande a été modifiée après le début du paiement), ou le paiement est arrivé après l'annulation de la commande. La note de commande l'explique. Vérifiez la transaction dans le Web Admin de Datatrans et exécutez la commande ou remboursez le paiement.

Failed: le paiement a échoué ou a été refusé. Le client peut réessayer.

Cancelled: l'autorisation a été libérée, par l'action de commande ou dans le Web Admin de Datatrans.

Une notification tardive d'échec ou d'annulation ne modifie jamais une commande payée. Si un second paiement réussi arrive pour une commande déjà payée, la commande n'est pas modifiée. Une note signale un possible double débit et vous demande de le rembourser dans Datatrans si nécessaire.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Datatrans. Les remboursements totaux et partiels sont pris en charge. Le remboursement est envoyé dans l'environnement où le paiement a été effectué ; les identifiants 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, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté aux notes de la commande avec le montant et l'ID de la transaction de remboursement Datatrans.

Pour un paiement seulement autorisé, le remboursement du montant total annule l'autorisation. Un remboursement partiel n'est pas possible tant que le paiement n'est pas capturé.

Les remboursements effectués dans le Web Admin de Datatrans ne sont pas enregistrés dans WooCommerce. Si nécessaire, créez un remboursement manuel dans WooCommerce sans Refund via Datatrans.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox de vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > Datatrans. 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 revérifier 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, Datatrans n'est pas affiché aux clients lors du paiement. Si un paiement est tout de même démarré, le client voit This payment method is not available. Please choose another one. Les gestionnaires de la boutique connectés voient toujours la méthode de paiement, marquée (unlicensed — visible to admins only), ce qui vous permet de configurer et de tester l'extension avant d'acheter une clé. Un rappel apparaît dans la page Extensions et dans les pages WooCommerce. Les commandes existantes ne sont pas affectées : les paiements déjà démarrés sont toujours confirmés, et les remboursements et captures fonctionnent.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est revérifié automatiquement en arrière-plan.

Dépannage

Datatrans n'apparaît pas lors du paiement : vérifiez que la licence est active, que Enable/Disable est activé et que le Merchant ID et le mot de passe d'API de l'environnement actuel sont renseignés : les champs sandbox en mode sandbox, les champs de production sinon. La page de réglages liste les champs manquants.

Le paiement est passé, mais la commande reste En attente de paiement : Datatrans n'a pas pu joindre l'URL du webhook et le client n'est pas revenu sur la boutique. Vérifiez que le site est accessible depuis internet en HTTPS et qu'aucune extension de sécurité ni aucun pare-feu ne bloque les requêtes vers /wc-api/datatrans_payment_callback/. Vérifiez que la clé de signature des réglages correspond à l'environnement du paiement. Activez Logging et consultez WooCommerce > Status > Logs, source wcp_datatrans_gateway.

Le webhook répond 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 de nouveau la clé.

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

La clé de signature HMAC n'est pas enregistrée : la clé doit être une chaîne hexadécimale. Copiez-la de nouveau depuis le Web Admin de Datatrans.

Le client voit The payment could not be started : le Merchant ID ou le mot de passe d'API est incorrect, appartient à l'autre environnement, ou la devise n'est pas activée pour votre compte Datatrans. Activez Logging pour voir la raison.

La commande est en attente après le paiement : lisez la note de la commande. Le montant ou la devise payés différaient de la commande, le paiement est arrivé après l'annulation de la commande, ou le paiement est seulement autorisé et attend la capture.

La capture est impossible : le total de la commande dépasse le montant autorisé. La capture utilise le total actuel de la commande ; réduisez-le donc au montant autorisé ou moins.

Le remboursement échoue avec un message sur les identifiants : le paiement a été effectué dans l'autre environnement et ses identifiants ne sont pas renseignés. Saisissez-les et réessayez. Pour un paiement autorisé, remboursez le montant total ou capturez-le d'abord.

Le bloc de licence affiche une erreur : suivez le message du 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.

Pour les développeurs, le readme mentionne le filtre wcp_datatrans_gateway_init_request, par exemple pour limiter les méthodes de paiement affichées sur la page Datatrans.

Désinstallation

Désactiver l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la dans 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 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.

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