Retour au blog E-commerce - 6 min

Erreur d’API de paiement : isoler la panne

Diagnostiquer une erreur d’API de paiement : séparer refus de carte, HTTP 4xx et 5xx, et webhooks qui ne confirment pas la commande.

Une erreur d’API de paiement n’est pas un message unique. Parfois la banque refuse la carte, parfois la boutique n’arrive pas à joindre le prestataire, parfois le paiement est pris et la commande ne passe jamais à « payée ». On sépare ces trois cas avec le code HTTP, l’identifiant de requête et le journal des webhooks.

Classer la réponse

Ce que vous voyezLectureAction
Motif carte, fonds, 3-D Secure abandonné, souvent avec un HTTP réussiRefus ou abandon métierRien à « réparer » côté serveur. Le client peut retenter. Ne relancez pas l’encaissement automatiquement.
HTTP 401 ou 403Clé API, signature ou horlogeClé de production sur le site de production, secret de webhook, heure du serveur proche de l’UTC
HTTP 422 ou 400 avec un champ citéRequête invalide (montant, devise, URL de retour)Corrigez le champ nommé. Un montant à virgule mal formée est un classique
HTTP 429Trop d’appelsFile d’attente, pas une deuxième salve immédiate
HTTP 500, 502, 504 ou délaiLe prestataire ou le réseauPage de statut du prestataire, puis nouvel essai avec le même identifiant d’idempotence s’il existe
Paiement « réussi » chez le prestataire, commande toujours en attenteWebhook non appliquéJournal d’envoi du prestataire et code de votre URL de notification

Ne journalisez pas le numéro de carte ni le cryptogramme. L’identifiant de paiement suffit à faire chercher le prestataire.

La page de commande qui renvoie elle-même un 500 avant même l’appel API est une panne boutique, à traiter comme dans trouver les erreurs 500. L’API n’a dans ce cas rien reçu.

Parcours de preuve

  1. Reproduisez avec une carte de test du prestataire, pas avec une carte client. Notez l’heure UTC et l’identifiant.
  2. Dans le journal applicatif, isolez la requête sortante : URL appelée (test ou production), code HTTP, corps d’erreur.
  3. Chez le prestataire, ouvrez ce même identifiant. S’il n’existe pas, l’appel n’est pas arrivé (DNS, TLS, mauvais hôte, pare-feu sortant). S’il existe, lisez son statut et la liste des notifications.
  4. Sur l’URL de webhook, vérifiez qu’un appel sans signature reçoit un 4xx rapide, et qu’un appel de test valide reçoit un 2xx tout de suite. Un traitement lourd avant le 200 fait croire au prestataire que vous êtes en délai : il réessaie, et vous doublez des commandes si l’idempotence n’est pas faite.
  5. Comparez l’URL configurée (https, bon hôte, pas l’URL d’une préproduction). Un certificat expiré sur cette URL casse les notifications même si le catalogue, servi par un CDN, a l’air sain. Contrôle : expiration du certificat.

Les redirections sur l’URL de retour navigateur se listent à part. Une boucle après le paiement renvoie le client sur une erreur alors que l’argent est pris : notez chaque code HTTP jusqu’à la page de confirmation, sans supposer que le dernier écran du navigateur est le premier saut.

Éviter le double encaissement

Quand vous rejouez un appel, utilisez la clé d’idempotence documentée par le prestataire. Un second POST « pour voir » sans cette clé peut créer un second paiement. Les réessais automatiques du webhook doivent reconnaître un identifiant déjà traité et répondre 200 sans recréer la commande.

Si toutes les commandes de l’heure restent en attente, ce n’est plus un refus de carte isolé. C’est le moment d’une alerte et d’un message au support : commande bloquée. Ouvrez la fiche d’incident avec l’identifiant de requête, pas avec une capture d’écran seule : documenter un incident.

Le correctif se revérifie par un paiement test de bout en bout : statut payé dans la boutique, un seul mouvement chez le prestataire, webhook en succès. Rejouez ensuite un webhook déjà traité : la boutique doit répondre succès sans créer une deuxième commande. C’est ce deuxième appel, pas le premier, qui montre si l’idempotence est vraiment en place.

Questions fréquentes

Un paiement refusé par la banque est-il une panne d’API ?

Non. La requête a souvent réussi (réponse HTTP 200 ou 402 selon le prestataire) avec un motif métier : fonds, 3-D Secure abandonné, carte expirée. La panne, c’est l’appel qui n’aboutit pas : délai, 401, 500, ou webhook jamais accepté.

Où trouver la preuve à envoyer au prestataire ?

L’identifiant de requête ou de paiement, l’heure en UTC, le code HTTP et le corps d’erreur sans données de carte. Le prestataire ne peut pas chercher « ça ne marche pas vers 15 h ».

Le client voit « paiement accepté » mais la commande reste en attente. Pourquoi ?

Le navigateur est revenu sur la boutique, mais le webhook qui marque la commande payée a échoué (signature, URL en 500, délai). Il faut lire la file d’envoi du prestataire, pas seulement l’écran de retour.

Surveiller mes URL