Intégrer une API de paiement sans se tromper

Une intégration de paiement se distingue d’une intégration ordinaire par un détail qui change tout : l’opération a des conséquences financières irréversibles, et le réseau ne garantit pas que vous saurez si elle a eu lieu. Une requête peut aboutir côté serveur et échouer côté client. Un délai d’attente dépassé n’est pas un échec, c’est une absence d’information. Toute la solidité d’une intégration tient dans la façon de traiter cette incertitude.

Règle 1 — Rendre chaque opération rejouable sans risque

Le scénario redouté est simple. Votre serveur envoie une demande de paiement. La connexion est coupée avant la réponse. Vous ne savez pas si le paiement a été créé. Si votre code réessaie naïvement, vous venez de débiter deux fois votre client.

La parade est une clé d’idempotence : un identifiant unique que vous générez vous-même et que vous joignez à la requête. Si la même clé revient, le serveur renvoie le résultat de la première opération au lieu d’en créer une seconde. Cette clé doit être dérivée de quelque chose de stable côté commerçant — une référence de commande, par exemple — et surtout pas d’un horodatage, qui changerait à chaque tentative et annulerait toute la protection.

Règle 2 — Attendre la notification, ne pas interroger en boucle

Un paiement mobile n’est pas instantané : le client doit valider sur son téléphone, l’opérateur doit répondre. Entre l’initiation et la confirmation, il s’écoule de quelques secondes à plusieurs minutes. Deux approches existent pour connaître l’issue, et elles ne se valent pas.

Interroger l’API en boucle jusqu’à obtenir un statut final fonctionne, mais consomme des requêtes, se heurte aux limitations de débit et introduit un délai proportionnel à la fréquence d’interrogation. Recevoir une notification signée dès que le statut change coûte un point d’entrée à exposer, et règle le problème. La règle pratique : le webhook est la source de vérité, l’interrogation directe est un filet de sécurité pour les cas où la notification ne serait pas arrivée.

Règle 3 — Vérifier la signature, toujours

Un point d’entrée qui reçoit des notifications de paiement est, par construction, une URL publique. N’importe qui peut y envoyer un message prétendant qu’un paiement de grande valeur a réussi. Si votre code fait confiance au contenu reçu, vous venez de créer un moyen gratuit de commander sur votre site.

Chaque notification doit donc porter une signature calculée avec un secret partagé, et votre code doit la recalculer avant de traiter quoi que ce soit. Deux précautions accompagnent cette vérification. La comparaison doit se faire à temps constant, sans quoi la durée de la réponse renseigne un attaquant sur la justesse de sa tentative. Et le secret utilisé doit être celui associé à l’émetteur enregistré côté serveur, jamais une valeur fournie dans le message lui-même — faute de quoi l’expéditeur choisit sa propre clé de vérification.

Règle 4 — Traiter l’échec comme un cas normal

Dans le paiement mobile, l’échec n’est pas une exception : c’est une issue fréquente et prévisible. Solde insuffisant, code de validation expiré, réseau indisponible, client qui abandonne devant son téléphone. Une intégration qui ne gère que le chemin heureux perd des ventes dont l’intention d’achat était pourtant réelle.

Concrètement : distinguez les statuts intermédiaires des statuts définitifs, et n’affichez jamais un paiement comme abouti tant que la confirmation n’est pas arrivée. Prévoyez une expiration explicite, faute de quoi des opérations resteront en attente indéfiniment et fausseront votre suivi. Et transmettez au client une raison compréhensible plutôt qu’un code technique, avec la possibilité de réessayer immédiatement.

Ce qu’il faut avoir testé avant de passer en production

Un environnement de test n’est utile que si l’on y rejoue autre chose que le succès. Avant toute mise en production, quatre scénarios méritent d’être passés : un paiement qui réussit, un paiement refusé, une notification reçue deux fois pour la même opération, et une notification portant une signature invalide. Si votre code se comporte correctement dans ces quatre cas, l’essentiel est couvert.

Enfin, séparez strictement les clés de test des clés de production, et ne conservez jamais une clé secrète en clair ailleurs que dans les variables d’environnement de votre serveur. Une clé secrète qui apparaît dans un dépôt de code, dans un fichier de configuration versionné ou dans le code exécuté par le navigateur doit être considérée comme compromise et remplacée immédiatement.