Menu

Guide

Clé HMAC perdue après une mise à jour : causes et prévention

Mis à jour le

Réponse courte

Les paiements Up2pay e‑Transactions (Paybox) échouent avec une erreur de signature HMAC juste après la mise à jour de votre extension de paiement ? Vérifiez d’abord la clé enregistrée. Elle a pu être effacée, remplacée ou ne plus être lue au bon endroit. Dans ce cas, ressaisissez la bonne clé, pour le bon mode (test ou production), puis faites un paiement de test. Si la clé est intacte, la nouvelle version calcule peut-être mal la signature (ordre des champs, valeurs encodées, XML modifiés). Ressaisir la clé ne changera alors rien : signalez-le à l’éditeur de l’extension. Pour la suite, gardez une copie sûre de vos clés et testez chaque mise à jour avant la production.

Pourquoi la clé compte autant

Chaque demande de paiement envoyée à la plateforme est signée avec votre clé HMAC. La plateforme recalcule cette signature avec la clé qu’elle connaît pour votre compte. Sans la bonne clé, la demande est refusée avec le message « Incohérence des paramètres / Accès refusé », accompagné de « Error while proceeding authentication with HMAC key ». Un code réponse 00006 (accès refusé, ou site, rang ou identifiant incorrect) peut aussi apparaître : le manuel Up2pay y associe la clé HMAC.

Deux précisions utiles :

  • il existe une clé pour la plateforme de recette (test) et une autre pour la production ;
  • d’après le manuel Paybox System (Verifone, v8.3), une clé expire un an après son activation, mais n’est pas désactivée automatiquement.

Les causes possibles

Chaque extension stocke ses réglages à sa façon. Les scénarios ci-dessous sont des mécanismes possibles, pas un constat sur une extension en particulier. Seul l’examen de votre site permet de trancher.

Une migration de réglages destructive

Lors d’une mise à jour, une extension peut transformer ses réglages pour les adapter à une nouvelle version : renommer un champ, en supprimer un, changer de format. Si cette étape remplace une valeur existante par une valeur par défaut, ou supprime un champ qu’elle croit inutile, la clé disparaît.

Un changement d’emplacement de stockage

Si une nouvelle version lit ses réglages sous un autre nom d’option que l’ancienne, l’ancienne clé est toujours en base mais n’est plus lue. Le champ paraît vide dans l’administration.

Un champ de clé vide enregistré par-dessus

Les champs de clé sont souvent masqués, comme un mot de passe. Si le formulaire renvoie un champ vide quand vous enregistrez un autre réglage, et que l’extension enregistre ce vide tel quel, la clé est effacée. La mise à jour n’est alors qu’une coïncidence : c’est le premier enregistrement des réglages après la mise à jour qui efface la clé.

Une désinstallation qui supprime les réglages

Certaines procédures de mise à jour manuelle passent par une suppression puis une réinstallation de l’extension. Si le script de désinstallation supprime les réglages, la clé part avec eux.

Une confusion de mode

Parfois, rien n’a été perdu. Si le mode est passé de test à production (ou l’inverse), l’extension utilise l’autre jeu d’identifiants, qui peut être vide ou ancien. La clé de l’autre mode est toujours là.

Un défaut de calcul de la signature

Parfois, la clé est intacte. La plateforme refuse aussi une signature calculée sur une chaîne qui ne correspond pas octet pour octet au formulaire envoyé : champs hachés dans un autre ordre que celui du formulaire, valeurs encodées URL au lieu des valeurs brutes, ou XML (PBX_SHOPPINGCART, PBX_BILLING) modifiés par l’échappement HTML. Une nouvelle version de l’extension peut introduire ce défaut. Ressaisir la clé ne règle alors rien : la correction se fait dans l’extension. Voir Erreur de signature HMAC Paybox.

Diagnostic pas à pas

  1. Confirmez qu’il s’agit bien du HMAC. Le message de la page de paiement doit contenir « HMAC key ». Sinon, le problème est ailleurs.
  2. Vérifiez le mode actif. Contrôlez que l’extension est dans le mode attendu, et que l’URL de destination du formulaire correspond : recette-tpeweb.e-transactions.fr (ou son alias preprod-tpeweb.e-transactions.fr) pour le test, tpeweb.e-transactions.fr ou tpeweb1.e-transactions.fr pour la production.
  3. Regardez le champ de la clé. Une extension peut ne jamais réafficher une clé enregistrée : son champ reste alors vide même quand la clé est en base. Si votre extension affiche d’habitude une valeur masquée et que le champ est vide, la clé a probablement été effacée ou n’est plus lue. Si le champ affiche une valeur masquée, comparez ses derniers caractères, s’ils sont visibles, avec ceux de la clé que vous avez conservée. S’ils correspondent, la clé n’est sans doute pas en cause : voyez le défaut de calcul de la signature ci-dessus.
  4. Vérifiez SITE, RANG et IDENTIFIANT. Une migration peut aussi avoir touché ces valeurs. Un code 00006 couvre ces trois réglages autant que la clé.
  5. Consultez le journal des modifications de l’extension pour voir si la mise à jour annonce un changement de réglages.
  6. Si vous avez une sauvegarde de la base de données d’avant la mise à jour, comparez les réglages de l’extension avant et après, sur une copie du site et jamais directement en production.

Solution

  1. Ressaisissez la clé du mode actif. Collez-la sans espace ni retour à la ligne. Elle ne contient que des caractères hexadécimaux. Pour les comptes de test publics, la clé de démonstration est publiée dans le document de test du Crédit Agricole. Elle est aussi fournie dans l’onglet « Paramètres » du back-office Vision de ces comptes.
  2. Ressaisissez aussi la clé de l’autre mode si elle a disparu, pour ne pas être surpris au prochain changement de mode.
  3. Faites un paiement de test. La page de paiement doit s’afficher sans message d’incohérence.
  4. Vérifiez les commandes passées depuis la mise à jour. Les clients qui ont reçu une erreur n’ont pas payé. Leurs commandes sont restées « En attente de paiement » (pending), ou WooCommerce les a annulées selon son réglage de réservation du stock. Vérifiez ces deux statuts.
  5. Signalez le problème à l’éditeur de l’extension avec les numéros de version avant et après, pour qu’il corrige la cause.

Prévention

  • Gardez une copie sûre de chaque clé, test et production, dans un gestionnaire de mots de passe, avec sa date d’activation.
  • Sauvegardez la base de données avant chaque mise à jour d’une extension de paiement.
  • Testez la mise à jour sur une copie du site avec le mode test, avant de l’appliquer en production.
  • Juste après la mise à jour sur le site en ligne, faites un paiement réel d’un faible montant, sans changer de mode, puis vérifiez le statut de la commande. À défaut, surveillez les premières commandes.
  • Ne désinstallez pas une extension de paiement pour la mettre à jour si vous ne savez pas ce que sa désinstallation supprime.

Ce que fait Relqor

Relqor — Gateway for Up2pay e‑Transactions, plugin indépendant non affilié à Verifone, Up2pay ou Crédit Agricole, suit ces règles :

  • migration uniquement additive : une mise à jour ajoute les réglages manquants avec leur valeur par défaut. Elle ne supprime, ne renomme et n’écrase jamais un réglage existant, clé HMAC comprise. Un réglage devenu inutile reste stocké ;
  • un seul emplacement de stockage, avec un numéro de version du schéma, pour que chaque version sache quelles étapes appliquer ;
  • champ de clé vide = clé conservée : enregistrer un autre réglage avec le champ de clé vide ne l’efface pas. La clé n’est jamais réaffichée en clair, seulement •••• suivi de ses 4 derniers caractères ;
  • désinstallation qui ne supprime rien, sauf si la constante RELQOR_REMOVE_ALL_DATA vaut true ;
  • jeux test et production distincts, chacun avec sa clé. Si les identifiants du mode actif manquent ou si sa clé est mal formée, le moyen de paiement n’est pas proposé au client, au lieu d’échouer sur la page de paiement.

Ces comportements sont couverts par des tests automatisés : mise à jour d’une version à la suivante avec clés identiques octet pour octet, champ vide qui conserve la clé, désinstallation qui laisse les réglages intacts. Le plugin Relqor pour Worldline Sips applique les mêmes règles à sa clé secrète.

Pour aller plus loin : la page Up2pay e‑Transactions pour WooCommerce et la documentation Mise à jour et désinstallation.