API idempotente : éviter les doublons lors des paiements et synchronisations

Une API idempotente traite plusieurs fois une même requête métier comme une seule opération effective. Pour les paiements, la méthode consiste à associer une clé d’idempotence unique à chaque opération, puis à mémoriser côté serveur le résultat déjà produit afin qu’une relance HTTP ne déclenche pas un second débit.

Ce mécanisme répond aux interruptions réseau, aux délais d’expiration, aux clics répétés, aux traitements concurrents et aux notifications reçues plusieurs fois. Le guide détaille la conception de la clé, le stockage durable, les verrous, l’intégration avec un prestataire de paiement et les tests à effectuer avant la mise en production.

Comprendre l’idempotence d’une API

L’idempotence est une propriété d’une opération qui produit le même effet métier lorsqu’elle est exécutée plusieurs fois que lorsqu’elle est exécutée une seule fois. Une API idempotente permet donc de rejouer une requête après une erreur réseau sans créer automatiquement une nouvelle opération.

Dans un paiement, une première requête peut être acceptée par le prestataire alors que la réponse n’arrive jamais jusqu’à l’application. Le client ne sait alors pas si le débit a réussi. Une nouvelle tentative sans mécanisme de déduplication peut créer un second paiement.

Une relance HTTP ne doit pas être interprétée comme une nouvelle opération métier lorsque le client réutilise la même clé d’idempotence.

Idempotence, unicité et atomicité : trois notions différentes

L’idempotence concerne le comportement lors des répétitions. L’unicité impose qu’une valeur, comme un identifiant de commande, ne puisse apparaître deux fois dans une table. L’atomicité garantit qu’un ensemble d’actions est validé entièrement ou annulé entièrement.

Une contrainte d’unicité peut empêcher deux lignes identiques, mais elle ne suffit pas à restituer la même réponse à une relance. Une transaction peut protéger l’écriture locale, mais elle ne contrôle pas directement le résultat obtenu auprès d’un prestataire de paiement externe.

Quelles méthodes HTTP sont idempotentes ?

La RFC 9110 classe généralement GET, PUT et DELETE comme méthodes idempotentes au niveau HTTP. POST n’est pas idempotente par défaut, car chaque appel peut créer une nouvelle ressource. Une API peut toutefois ajouter une clé d’idempotence à POST pour rendre son opération métier rejouable sans duplication.

Méthode	Comportement HTTP	Point de vigilance
GET	Lecture répétable	Éviter les effets de bord cachés
PUT	Remplacement d’une ressource ciblée	Utiliser un identifiant stable
DELETE	Suppression répétable	Définir clairement le statut d’une ressource déjà supprimée
POST	Non idempotente par défaut	Ajouter une clé d’idempotence pour une création rejouable
PATCH	Variable selon l’opération	Documenter précisément l’effet d’une répétition

La référence normative à consulter est la RFC 9110 sur la sémantique HTTP. La classification du protocole ne garantit pas, à elle seule, que le code applicatif respecte réellement l’idempotence.

Pourquoi les paiements et synchronisations créent-ils des doublons ?

Les doublons apparaissent lorsqu’une même opération est rejouée sans identifiant commun ni contrôle atomique. Les délais d’attente, les erreurs de connexion, les boutons activés plusieurs fois et les files à livraison au moins une fois rendent ces répétitions normales dans une architecture distribuée.

• Le navigateur ou l’application mobile relance une requête après un délai d’expiration.
• Un utilisateur clique deux fois sur le bouton de paiement.
• Un worker reprend un message dont l’accusé de réception n’a pas été confirmé.
• Un webhook est envoyé plusieurs fois après une réponse non reçue.
• Deux instances traitent simultanément la même commande.

Une architecture distribuée fonctionne souvent avec des relances, car une réponse absente ne permet pas de distinguer immédiatement un échec d’un succès déjà enregistré. La bonne question n’est donc pas « comment éviter toute relance ? », mais « comment rendre une relance sûre ? ».

Pour approfondir la reprise après incident, consultez cette méthode de gestion des erreurs et reprises API. L’idempotence en constitue une brique, pas un remplacement complet.

Comment concevoir une clé d’idempotence fiable ?

Une clé d’idempotence est un identifiant unique généré par le client pour une opération métier précise. Le client réutilise cette clé uniquement lorsqu’il rejoue exactement la même opération, tandis que le serveur vérifie que la clé n’est pas associée à un autre contenu.

Générer une clé par opération métier

Le client doit créer une clé avant le premier envoi, puis la conserver pendant toute la durée des tentatives. Un UUID aléatoire constitue un format courant, à condition que l’application génère une clé différente pour deux paiements réellement distincts.

POST /paiements
Idempotency-Key: 4f8c2c6e-7d91-4e7a-9a1d-2f0d8b7c61aa
Content-Type: application/json

{
  "commande_id": "CMD-2026-00481",
  "montant": 4990,
  "devise": "EUR"
}

Cet exemple utilise un montant exprimé en centimes et une commande fictive. Une clé ne doit pas contenir de numéro de carte, de secret ou de donnée personnelle inutile.

Associer la clé à une empreinte de requête

Le serveur doit enregistrer une empreinte du contenu pertinent, par exemple la commande, le montant, la devise et le compte concerné. Une seconde requête portant la même clé mais un montant différent doit être rejetée plutôt que traitée comme une nouvelle intention.

• Clé d’idempotence.
• Empreinte du corps normalisé.
• Identifiant du compte ou du marchand.
• Statut de traitement.
• Réponse sérialisée ou identifiant du résultat.
• Date de création et date d’expiration.

La clé identifie l’opération, tandis que l’empreinte vérifie que la relance correspond bien à la même demande. Cette distinction évite qu’un client réutilise par erreur une clé pour une autre commande.

Comment traiter une relance côté serveur ?

Le serveur doit rechercher la clé avant de lancer l’opération métier, réserver son traitement de manière atomique, puis enregistrer le résultat. Une relance identique renvoie la réponse déjà stockée ; une requête concurrente attend ou reçoit un statut temporaire au lieu de créer une seconde opération.

Étape 1 : recevoir et valider la clé

Le serveur exige une clé sur les opérations susceptibles de créer un paiement, une commande ou une écriture. La validation vérifie le format, la longueur, le contexte d’utilisation et l’authentification du client.

Une clé absente peut provoquer une réponse de validation, par exemple un statut HTTP 400, si l’opération exige une protection contre les répétitions. Le serveur ne doit pas fabriquer silencieusement une clé différente à chaque tentative, car la relance deviendrait impossible à rattacher au premier appel.

Étape 2 : réserver la clé dans un stockage durable

Le serveur insère la clé et son empreinte dans une table protégée par une contrainte d’unicité. L’insertion doit être atomique : deux instances qui reçoivent la même clé ne doivent pas pouvoir constater simultanément qu’elle est libre.

INSERT INTO idempotence
  (cle, empreinte, statut, expire_le)
VALUES
  (:cle, :empreinte, 'en_cours', :expiration)
ON CONFLICT (cle) DO NOTHING;

Le pseudo-code illustre le principe, mais la syntaxe exacte dépend du moteur de base de données. Une vérification suivie d’une insertion séparée est insuffisante en environnement distribué, car deux requêtes concurrentes peuvent passer le contrôle avant l’écriture.

Étape 3 : exécuter l’opération et stocker la réponse

L’application traite le paiement ou la synchronisation après la réservation. Le résultat métier, le statut HTTP et les éléments nécessaires à la réponse sont associés à la clé. Une relance ultérieure peut alors restituer le même résultat sans rappeler inutilement le prestataire.

Le stockage doit distinguer au minimum les états « en cours », « réussi », « échoué définitivement » et « résultat inconnu ». Un arrêt après le débit mais avant l’écriture locale produit un cas incertain qui demande une vérification auprès du prestataire, pas une nouvelle charge automatique.

Étape 4 : répondre à une relance identique

Une requête utilisant une clé déjà terminée récupère l’empreinte et le résultat enregistré. Si l’empreinte correspond, le serveur renvoie la réponse mémorisée. Si l’empreinte diffère, le serveur rejette la requête pour empêcher une réutilisation ambiguë de la clé.

La réponse peut reprendre le même code HTTP que la première exécution. Une API doit documenter le comportement d’une requête concurrente encore en cours : attente courte, réponse temporaire ou mécanisme de consultation du statut.

La déduplication fiable repose sur trois éléments liés : une clé stable, une réservation atomique et une réponse persistée.

Comment éviter les doublons de paiement avec un prestataire externe ?

Pour sécuriser un paiement, l’application doit transmettre une identité d’opération cohérente à son prestataire, conserver la correspondance entre commande et paiement, puis rapprocher les statuts reçus. Une clé locale réduit les doublons côté application, mais la protection dépend aussi du support d’idempotence du prestataire et du traitement des notifications.

Coordonner l’application et le prestataire

Une commande interne doit posséder un identifiant stable, distinct de la clé technique envoyée dans l’en-tête. L’application conserve ensuite l’identifiant retourné par le prestataire, le montant demandé, la devise et l’état observé.

Les prestataires de services de paiement acceptent généralement des mécanismes de clé d’idempotence, mais les règles de durée, de réutilisation et de réponse varient selon leur documentation. La documentation officielle du prestataire utilisé doit primer sur toute règle générale.

Par exemple, la documentation de Stripe sur les requêtes idempotentes indique une conservation des clés pendant 24 heures dans son contexte. Cette durée ne doit pas être généralisée à tous les PSP.

Traiter les notifications répétées

Un webhook doit lui aussi être dédupliqué. Le serveur enregistre l’identifiant de l’événement, vérifie sa signature, refuse les événements déjà traités et applique une transition d’état contrôlée. Une notification reçue deux fois ne doit pas déclencher deux confirmations de commande ou deux remboursements.

La réception d’un événement ne prouve pas toujours que l’état local est complet. Pour les opérations sensibles, l’application peut consulter le statut auprès du prestataire avant de confirmer définitivement la commande.

Comment rendre une synchronisation sans doublon ?

Une synchronisation idempotente utilise un identifiant stable par objet et une règle claire de mise à jour. Le système ne crée pas une nouvelle ligne à chaque reprise : il retrouve l’objet existant, compare sa version ou son empreinte, puis applique uniquement la transition nécessaire.

Synchroniser avec un identifiant stable

Une fiche client, une facture ou une commande doit transporter un identifiant source conservé entre les tentatives. Une contrainte d’unicité sur le couple « système source, identifiant source » protège la base locale contre les insertions répétées.

Le choix entre webhook et interrogation périodique dépend aussi du besoin de fraîcheur, du volume et de la capacité à rejouer les événements. Cette comparaison entre webhook et interrogation périodique aide à cadrer ce choix.

Reprendre une synchronisation interrompue

Une reprise doit repartir d’un curseur, d’un identifiant de page ou d’une date de modification clairement définie. Chaque élément traité reçoit un statut local. Le système peut alors relancer les éléments « en attente » ou « incertains » sans recréer ceux qui sont déjà confirmés.

• Utiliser un identifiant source immuable.
• Ajouter une contrainte d’unicité en base.
• Conserver le dernier curseur validé.
• Rendre chaque transformation répétable.
• Journaliser les éléments ignorés, créés ou mis à jour.

Comment gérer les erreurs et la durée de conservation des clés ?

La durée de conservation doit couvrir la période pendant laquelle une relance reste possible, sans conserver indéfiniment des données opérationnelles. Une valeur de 24 heures est utilisée par certains services de paiement, mais le choix réel dépend du prestataire, du délai de reprise et du risque métier.

Différencier échec certain et résultat incertain

Un refus explicite avant traitement peut être rejoué avec la même clé si la documentation du prestataire l’autorise. Une coupure après l’envoi du paiement produit un résultat incertain : l’application doit d’abord rechercher le statut existant avant d’envoyer une nouvelle demande.

La suppression prématurée d’une clé augmente le risque qu’une relance tardive soit considérée comme une nouvelle opération. À l’inverse, une conservation trop longue augmente le volume du stockage et peut compliquer la gestion des données sensibles.

Gérer la concurrence avec un verrou adapté

Une base de données peut fournir la réservation atomique lorsque le périmètre est local. Plusieurs services ou régions peuvent nécessiter un mécanisme de verrou distribué avec expiration. Le délai du verrou doit dépasser la durée maximale d’une réservation, faute de quoi une seconde instance pourrait reprendre la clé avant la fin du premier traitement.

Le verrou ne remplace pas l’enregistrement durable du résultat. Il protège une fenêtre critique ; la contrainte d’unicité et la réponse persistée assurent la déduplication après redémarrage.

Comment tester une API idempotente avant sa mise en production ?

Un test d’idempotence vérifie qu’une même opération conserve un seul effet métier malgré des relances, des erreurs et des appels simultanés. Les tests doivent observer la base locale, les appels au prestataire, les réponses HTTP et les notifications, plutôt que de vérifier uniquement le code de statut.

1. Envoyer une première requête avec une clé unique et vérifier la création d’un seul résultat.
2. Renvoyer exactement la même requête avec la même clé et comparer la réponse.
3. Renvoyer la même clé avec un montant ou un corps différent et vérifier le rejet.
4. Lancer plusieurs requêtes simultanées avec la même clé et compter les opérations externes.
5. Simuler une interruption après le traitement externe, puis vérifier la récupération du statut.
6. Attendre ou simuler l’expiration de la clé et vérifier la règle documentée.

Les journaux doivent contenir la clé sous une forme contrôlée, l’identifiant de commande, le statut, la latence et le motif d’une relance. Les secrets, les numéros de carte et les données sensibles ne doivent pas être écrits en clair dans les traces.

Quelles erreurs fréquentes faut-il éviter ?

Les erreurs d’idempotence viennent souvent d’une protection placée au mauvais endroit. Un contrôle applicatif isolé peut sembler fonctionner en test unitaire, puis échouer lorsque plusieurs instances ou workers traitent la même clé.

• Vérifier puis insérer sans atomicité : deux requêtes concurrentes peuvent passer le contrôle avant l’écriture. Utilisez une contrainte d’unicité ou une opération atomique.
• Stocker la clé uniquement en mémoire : un redémarrage ou un autre nœud oublie l’opération. Utilisez un stockage durable adapté.
• Générer une nouvelle clé à chaque relance : le serveur ne peut plus reconnaître la répétition. Conservez la clé côté client.
• Modifier silencieusement le corps avec la même clé : une même clé devient ambiguë. Rejetez les empreintes différentes.
• Confondre réponse reçue et paiement confirmé : une erreur réseau peut survenir après le traitement. Consultez le statut avant toute nouvelle tentative.

La sécurité de l’API reste également distincte de l’idempotence. L’authentification et les autorisations doivent empêcher qu’un tiers réutilise une clé dans un autre contexte. Pour cadrer cette partie, consultez ce guide sur les mécanismes d’authentification API.

Quelle approche choisir entre clé d’idempotence, PUT et contrainte d’unicité ?

La clé d’idempotence convient aux créations POST et aux opérations où le client doit rejouer une demande. PUT convient lorsqu’une ressource possède déjà une adresse stable. La contrainte d’unicité protège la base dans les deux cas, mais ne restitue pas seule la réponse d’une requête précédente.

Approche	Cas adapté	Limite
Clé d’idempotence	Paiement ou création POST rejouable	Gestion du stockage, de l’expiration et des conflits
PUT avec identifiant stable	Remplacement d’une ressource connue	Moins adapté à une opération financière sans ressource préalable
Contrainte d’unicité	Déduplication locale en base	Ne gère pas seule les appels externes ni la réponse mémorisée

Pour une API de paiement, la combinaison la plus robuste associe généralement une clé d’idempotence, une contrainte d’unicité locale, une transaction adaptée et un rapprochement avec le prestataire. Le choix final dépend du modèle de données et du contrat de l’API externe.

Questions fréquentes

Une API idempotente empêche-t-elle toujours un double débit ?

Non. L’idempotence réduit le risque lorsqu’elle est correctement implémentée côté application et prise en charge par le prestataire. Les transactions, les notifications, les rapprochements de statuts et les règles du PSP restent nécessaires.

Où stocker une clé d’idempotence ?

La clé doit être conservée dans un stockage persistant accessible par les instances qui traitent l’API. La ligne doit inclure au minimum l’empreinte de la requête, le statut, le résultat et la date d’expiration.

Peut-on réutiliser une clé après une erreur ?

La même clé doit servir à rejouer exactement la même opération lorsque le résultat est incertain. Une nouvelle intention métier, un autre montant ou une autre commande nécessite une nouvelle clé.

Quelle différence entre idempotence et transaction ?

L’idempotence contrôle les répétitions d’une opération. Une transaction garantit la cohérence d’un groupe d’écritures dans une base, mais ne suffit pas à synchroniser automatiquement une base locale et un prestataire externe.

Combien de temps conserver une clé d’idempotence ?

La durée dépend du délai de reprise attendu et du prestataire utilisé. Certains services documentent 24 heures, mais cette valeur ne doit pas être appliquée sans vérifier le contrat de l’API concernée.

Sources utiles à consulter

RFC 9110 → sémantique des méthodes HTTP → vérifier les propriétés d’idempotence du protocole.

Documentation Stripe → comportement des clés dans ce PSP → vérifier la durée de conservation et les réponses aux relances.

Google Cloud → principes généraux de l’idempotence → comparer les mécanismes de reprise dans les architectures distribuées.

Versionner une API sans rupture → gestion de l’évolution des contrats → éviter qu’une modification d’API invalide le mécanisme de relance.