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 voyez | Lecture | Action |
|---|---|---|
| Motif carte, fonds, 3-D Secure abandonné, souvent avec un HTTP réussi | Refus ou abandon métier | Rien à « réparer » côté serveur. Le client peut retenter. Ne relancez pas l’encaissement automatiquement. |
| HTTP 401 ou 403 | Clé API, signature ou horloge | Clé 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 429 | Trop d’appels | File d’attente, pas une deuxième salve immédiate |
| HTTP 500, 502, 504 ou délai | Le prestataire ou le réseau | Page 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 attente | Webhook 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
- Reproduisez avec une carte de test du prestataire, pas avec une carte client. Notez l’heure UTC et l’identifiant.
- Dans le journal applicatif, isolez la requête sortante : URL appelée (test ou production), code HTTP, corps d’erreur.
- 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.
- Sur l’URL de webhook, vérifiez qu’un appel sans signature reçoit un
4xxrapide, et qu’un appel de test valide reçoit un2xxtout de suite. Un traitement lourd avant le200fait croire au prestataire que vous êtes en délai : il réessaie, et vous doublez des commandes si l’idempotence n’est pas faite. - 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.
