Menu

Guide

Erreur de signature HMAC Paybox : comprendre et corriger

Mis à jour le

Réponse courte

Le message « Incohérence des paramètres / Accès refusé » s’accompagne de la mention « Error while proceeding authentication with HMAC key ». Il signifie que la plateforme Paybox (Up2pay e‑Transactions pour le Crédit Agricole) a recalculé l’empreinte PBX_HMAC de votre demande. Elle n’a pas obtenu la même valeur que votre site. Les causes à vérifier en premier sont une mauvaise clé (clé de test en production, ou l’inverse), une clé mal saisie, ou une chaîne hachée qui ne correspond pas octet pour octet à ce qui est réellement envoyé.

Comment la signature est calculée

Chaque demande de paiement envoyée à la page de paiement hébergée est signée. Le manuel d’intégration Paybox System (Verifone, v8.3) et le manuel d’intégration Up2pay e‑Transactions (Crédit Agricole) décrivent le même calcul :

  1. On concatène toutes les variables envoyées, sauf PBX_HMAC, sous la forme NOM=valeur, séparées par &, dans l’ordre exact des champs du formulaire.
  2. On utilise les valeurs brutes, sans encodage URL.
  3. La clé, fournie en hexadécimal, est convertie en binaire avant usage. La clé sous forme de texte n’est pas la clé HMAC.
  4. On calcule le HMAC avec l’algorithme annoncé dans PBX_HASH (par exemple SHA512) et on envoie le résultat en hexadécimal dans PBX_HMAC.

Voici la forme de la chaîne hachée, avec des valeurs remplacées par des points de suspension :

PBX_SITE=…&PBX_RANG=…&PBX_IDENTIFIANT=…&PBX_TOTAL=…&…&PBX_HASH=SHA512&PBX_TIME=…

La plateforme refait ce calcul avec la clé qu’elle connaît pour votre compte. Si un seul octet diffère, dans la clé ou dans le message, les empreintes ne correspondent pas.

Ce qui a été vérifié sur la plateforme de recette

Des essais réalisés le 24/09/2026 sur la plateforme de recette Up2pay, avec le compte de test public, précisent plusieurs points :

  • un HMAC faux est refusé avec « Incohérence des paramètres / Accès refusé — Error while proceeding authentication with HMAC key » ;
  • un HMAC correct écrit en minuscules est accepté : la casse n’est pas en cause ;
  • un PBX_TIME avec un fuseau +02:00 est accepté : le fuseau n’est pas en cause ;
  • l’ordre des champs est libre, à condition que la chaîne hachée suive exactement l’ordre du formulaire (un ordre différent est refusé) ;
  • un HMAC calculé sur des valeurs encodées URL est refusé.

Les messages qui ne sont pas une erreur de HMAC

Tous les refus ne viennent pas de la signature. Par exemple, un PBX_RETOUR de plus de 150 caractères donne aussi une « incohérence des paramètres ». D’autres refus portent un message précis sur un champ, comme « is more than 3 characters long » pour un rang trop long, ou « is more than 80 characters long » pour un e‑mail trop long. Lisez le texte complet de la page d’erreur : la mention « HMAC key » désigne la signature, alors qu’un message qui cite un champ désigne ce champ.

Diagnostic pas à pas

  1. Notez le message exact. S’il mentionne « Error while proceeding authentication with HMAC key », continuez. Sinon, cherchez le champ cité dans le message.
  2. Vérifiez le couple serveur et clé. Il existe une clé pour la plateforme de recette et une autre pour la production. Une clé de test envoyée au serveur de production, ou l’inverse, est refusée. Contrôlez le mode actif de votre extension et l’URL de destination du formulaire. Pour Up2pay e‑Transactions : recette-tpeweb.e-transactions.fr pour le test, tpeweb.e-transactions.fr ou tpeweb1.e-transactions.fr pour la production. Hors Up2pay, avec Paybox System (Verifone), les adresses sont différentes : utilisez celles indiquées dans le manuel Paybox System.
  3. Vérifiez SITE, RANG et IDENTIFIANT. SITE compte 7 chiffres, RANG 2 ou 3 chiffres, IDENTIFIANT 1 à 9 chiffres. Utilisez la clé fournie avec ces identifiants, pour le même mode, et pas une clé d’un autre compte ou d’un ancien réglage.
  4. Vérifiez la forme de la clé. Elle ne doit contenir que des caractères hexadécimaux (0-9, A-F), sans espace, sans retour à la ligne, avec une longueur paire. Un copier-coller depuis un e‑mail ou un PDF ajoute parfois un espace ou un saut de ligne. La clé de démonstration publiée par le Crédit Agricole fait 128 caractères hexadécimaux.
  5. Vérifiez PBX_HASH. L’algorithme annoncé doit être celui qui a servi au calcul. La plateforme admet SHA512, SHA256, RIPEMD160, SHA384, SHA224 et MDC2.
  6. Comparez la chaîne hachée au formulaire réellement envoyé. Ouvrez le code source de la page intermédiaire et relevez les champs dans l’ordre. La chaîne hachée doit reprendre exactement ces champs, dans cet ordre, avec les mêmes valeurs.
  7. Cherchez les altérations d’encodage. Deux pièges sont à contrôler :
    • un calcul fait sur des valeurs encodées URL, alors que la règle impose les valeurs brutes ;
    • un échappement HTML qui modifie les valeurs XML (PBX_SHOPPINGCART, PBX_BILLING). Une fonction qui ne ré-encode pas les entités déjà présentes, comme & ou ', fait envoyer par le navigateur un XML différent de celui qui a été haché.
  8. Testez avec une commande simple. Un nom sans apostrophe ni esperluette, une adresse sans caractère spécial. Si cette commande passe et qu’une autre échoue avec le même message HMAC, la clé n’est pas en cause : cherchez du côté des champs de cette commande (encodage, ou caractère que la plateforme n’accepte pas).

Solution

  • Mauvaise clé ou mauvais mode : ressaisissez la clé qui correspond au mode et au compte actifs. Gardez deux jeux distincts, un pour le test et un pour la production.
  • Clé mal formée : collez-la de nouveau, sans espace ni retour à la ligne, et vérifiez qu’elle ne contient que des caractères hexadécimaux.
  • Ordre ou encodage : le calcul doit partir d’une seule liste ordonnée de champs, utilisée à la fois pour la chaîne hachée et pour le formulaire. C’est une correction à faire dans l’extension de paiement, pas dans vos réglages. Si vous n’en êtes pas l’auteur, transmettez à son éditeur le message d’erreur et un exemple de commande qui échoue.

Prévention

  • Conservez vos clés dans un endroit sûr, séparées par mode, et ne les envoyez jamais par e‑mail ou par ticket de support.
  • Notez la date d’activation de chaque clé. D’après le manuel Paybox System, une clé expire 1 an après son activation, mais n’est pas désactivée automatiquement.
  • Après toute modification des réglages, vérifiez que la page de paiement s’affiche dans le mode que vous avez modifié. Un paiement en mode test n’utilise que le jeu de test : il ne contrôle ni la clé ni les identifiants de production.
  • Testez des commandes avec des accents, des apostrophes et une esperluette dans le nom et l’adresse.

Ce que fait Relqor

Relqor — Gateway for Up2pay e‑Transactions est un plugin indépendant, non affilié à Verifone, Up2pay ou Crédit Agricole. Il applique le calcul décrit ci-dessus :

  • une seule structure ordonnée alimente la chaîne hachée et le formulaire ;
  • les valeurs sont hachées brutes, avec HMAC-SHA512 (PBX_HASH=SHA512) et une clé hexadécimale convertie en binaire ;
  • les valeurs du formulaire sont échappées de façon que le navigateur envoie les champs XML (PBX_SHOPPINGCART, PBX_BILLING) tels qu’ils ont été hachés ;
  • la clé est validée à la saisie : hexadécimal uniquement, espaces et retours à la ligne retirés, avertissement si sa longueur est différente de 128 caractères ;
  • le calcul a été accepté par la plateforme de recette le 24/09/2026 : le message et l’empreinte acceptés sont conservés, et un test automatisé, lancé lorsque la clé de démonstration est fournie, vérifie que le calcul redonne cette empreinte ;
  • en cas de code 00006, la note de commande et le journal indiquent « Accès refusé ou site/rang/identifiant incorrect (vérifier aussi la clé HMAC) ».

Pour aller plus loin : la page Up2pay e‑Transactions pour WooCommerce, la documentation Installation et réglages et la fiche d’erreur « Incohérence des paramètres / Accès refusé ».