Pourquoi le webhook PSP est la source de vérité du paiement

C'est la règle la plus simple de tout le commerce en ligne, et celle qu'on voit le plus souvent enfreinte.

Ce qui se passe réellement au moment de payer

Un paiement en ligne met en scène trois acteurs qui ne se parlent pas tous au même moment.

navigateur  ---(1) va payer--->  PSP
                                  |
      <---(2) redirection---------|
                                  |
votre serveur  <--(3) notification signée--
                     (serveur a serveur)

Le chemin (2) passe par la machine du client. Le chemin (3) part du PSP vers votre serveur. Ils sont indépendants, et rien ne garantit leur ordre.

En pratique, le navigateur revient souvent avant la notification. Parfois il ne revient jamais : l'onglet est fermé, le réseau tombe, l'application bancaire garde la main. Le paiement, lui, a bien eu lieu.

Ce que le retour du navigateur ne prouve pas

Une redirection est une URL. Elle est visible, modifiable, rejouable.

Un service qui marque une commande payée sur la foi d'un retour de navigateur accepte donc que n'importe qui, en recopiant l'adresse de confirmation, obtienne une commande payée sans avoir payé. Ce n'est pas une hypothèse d'école : c'est la première chose que tente quiconque regarde une barre d'adresse.

Ce que la notification apporte, et ce qu'elle exige

Le message du PSP est signé avec un secret partagé, connu de lui et de vous. Une signature valide prouve deux choses : le message vient bien du PSP, et il n'a pas été modifié en route.

D'où trois obligations côté serveur.

1. Vérifier la signature avant de lire le contenu. Un message dont la signature ne tombe pas juste ne doit rien déclencher, et doit répondre en erreur.

2. Être idempotent. Un PSP réessaie quand il n'obtient pas de réponse : le même paiement peut donc arriver deux fois. Le second passage ne doit produire ni seconde facture, ni second email.

3. Comparer le montant. Un message authentique peut annoncer un montant qui ne correspond pas à la commande enregistrée : le total de référence est celui que votre serveur a calculé, jamais celui qui revient.

Comment Ts-Shop applique la règle

Le secret de webhook est traité comme la clé secrète : sans lui, la boutique ne peut pas être publiée. La raison est directe : avec la clé secrète seule, on sait ouvrir un paiement, pas apprendre qu'il a eu lieu. Une boutique en ligne dans cet état prendrait des commandes qui resteraient en attente de paiement pour toujours, sans que rien ne l'explique.

La page de confirmation du checkout hébergé interroge la commande au lieu de croire l'URL sur laquelle elle est arrivée. Le client qui revient trop tôt voit « paiement en cours de confirmation », et la page se met à jour quand la notification est arrivée.

Le cas des PSP sans webhook signé

Tous les prestataires ne signent pas. Certains rappellent une URL qui porte un jeton dans son chemin. C'est acceptable à deux conditions : le jeton est imprévisible, et il n'est jamais stocké en clair chez vous. On garde son empreinte, comme un mot de passe, et on compare les empreintes.

Ce qui reste inacceptable, dans tous les cas, c'est de conclure à partir d'une URL que le client peut fabriquer.

Questions courantes

Faut-il exposer l'URL de notification publiquement ? Oui, et ce n'est pas un problème : elle n'a pas besoin d'être secrète, puisque c'est la signature qui authentifie le message. Les clés, elles, le sont.

Que faire d'une notification dont la signature est invalide ? Répondre une erreur et journaliser. Surtout pas répondre « reçu » : le PSP cesserait de réessayer.

Et si la notification n'arrive jamais ? Les PSP réessaient plusieurs fois. Au-delà, la commande reste en attente et se rattrape en interrogeant le PSP sur son état, jamais en la marquant payée par défaut.

Pour aller plus loin

• Comment ajouter l'e-commerce à un site existant
• La documentation de votre PSP sur la vérification de signature : c'est elle qui fait foi sur l'algorithme et sur l'ordre exact des octets signés.