Introduction

Dans les services web, les requêtes idempotentes garantissent que le résultat d'une requête effectuée avec succès est indépendant du nombre de fois où elle a été exécutée. Cela est particulièrement important pour soumettre des demandes de paiement : envoyer une CreateHostedCheckout/CreatePayment pour une commande spécifique accidentellement plusieurs fois ne débite vos clients qu'une seule fois.

Mettre en œuvre des requêtes idempotentes

Pour garantir qu'une requête ne soit traitée qu'une seule fois, vous devez inclure un identifiant unique dans l'en-tête HTTP de votre requête. Cet identifiant est appelé la clé qui :

• Doit être unique pour chaque transaction afin de garantir que la requête ne soit traitée qu'une seule fois.
• A une longueur maximale de 40 caractères.
• Doit être conforme à l'ASCII et ne pas supporter UTF-8.

Résultats possibles des requêtes idempotentes

• Pour les requêtes traitées : Notre serveur répondra avec le même résultat que la requête initiale, même avec des payloads différents. Les mises à jour liées à l'opération, telles que le statut du paiement, peuvent toujours se produire.
• Pour les requêtes en cours : Une réponse avec un code de statut HTTP de 409 (Conflit) indiquera que la requête est actuellement en cours de traitement. Assurez-vous de gérer ce scénario dans votre application.

En-têtes de réponse pour les requêtes ultérieures 

Pour toute demande de suivi faite avec la même clé d'idempotence, notre réponse inclut un en-tête supplémentaire, X-GCS-Idempotence-Request-Timestamp. Cet en-tête indique l'horodatage de la demande initiale en millisecondes depuis le 1er janvier 1970 00:00:00 UTC. 

Méthodes prises en charge

Les méthodes API suivantes prennent en charge les requêtes idempotentes :

• CreatePayment
• CancelPayment
• RefundPayment
• CapturePayment
• CompletePayment
• CreatePayout
• SubsequentPayment