Skip to main content

​
Vue d’ensemble

Dodo Payments renvoie une raison détaillée de l’échec chaque fois qu’une tentative de paiement échoue. Ces raisons sont standardisées entre les moyens de paiement et les prestataires, afin que vous puissiez mettre en œuvre une gestion cohérente dans votre application. Lorsqu’un paiement échoue, le webhook payment.failed et l’objet de paiement exposent :
  • error_code — un motif d’échec standardisé issu du tableau ci-dessous.
  • error_message — une explication compréhensible rédigée pour vous, le marchand. Lorsque error_code correspond à l’un des codes standardisés ci-dessous, il s’agit d’un titre accompagné de l’action recommandée, et non du texte brut du processeur de paiement.
  • retry_attempt — 0 pour le débit initial, 1 ou plus pour chaque nouvelle tentative de renouvellement d’abonnement planifiée.
Comprendre ces raisons d’échec vous permet de fournir aux clients des informations claires, de déterminer si une nouvelle tentative est pertinente et de récupérer davantage de revenus.

​
Texte destiné au marchand et texte destiné au client

Chaque code d’échec standardisé correspond à deux messages différents, afin que chaque audience voie le niveau de détail approprié :
Le Customer Portal renvoie le texte destiné au client dans error_message, tandis que l’API du marchand renvoie le texte destiné au marchand pour le même paiement. error_code est identique dans les deux cas.

Handle Payment Failures

Un guide développeur détaillé expliquant comment lire ces codes depuis les webhooks et l’API, les afficher aux clients et déterminer quand effectuer une nouvelle tentative.

​
Refus temporaires et définitifs

Chaque code d’échec appartient à l’une de deux catégories. Cette distinction détermine si vous devez réessayer avec le même moyen de paiement ou demander au client d’en utiliser un autre. Pour les renouvellements d’abonnement, Dodo Payments applique automatiquement cette distinction : les refus temporaires font l’objet de nouvelles tentatives via Subscription Payment Retries, tandis que les refus définitifs mettent immédiatement fin à la chaîne de tentatives et sont mieux traités avec Subscription Dunning.
Ne révélez jamais au client la véritable raison de STOLEN_CARD, LOST_CARD, PICKUP_CARD ou FRAUDULENT. Leur affichage pourrait renseigner un acteur frauduleux. Affichez toujours au client un message de refus générique (par exemple : “Votre carte a été refusée. Veuillez contacter votre banque ou utiliser une autre carte.”) et consignez uniquement le code spécifique en interne.Dodo Payments applique déjà cette règle sur les interfaces qu’il contrôle : pour ces quatre codes, le checkout, le Customer Portal et les e-mails de relance de paiement utilisent toujours un message de refus générique, tandis que votre propre texte conserve la véritable raison. Appliquez la même règle partout où vous affichez error_message de l’API du marchand à un client.

​
Motifs d’échec des transactions

Le tableau suivant répertorie chaque code d’échec, son type de refus, la possibilité pour le client de le résoudre, sa description et l’action recommandée.
Erreur utilisateur indique si le refus du paiement peut être résolu par le client. Lorsque Yes, le client peut agir pour résoudre le problème (par exemple, en saisissant correctement les informations de sa carte). Lorsque No, le refus est dû à des problèmes système ou à des restrictions bancaires que le client ne peut pas résoudre directement.
Une carte peut également être refusée lorsque le moteur de gestion des risques de la banque émettrice signale le titulaire comme présentant un risque élevé — indépendamment du marchand ou des détails de la transaction. Ces refus apparaissent généralement sous la forme de codes génériques tels que DO_NOT_HONOR, GENERIC_DECLINE, CARD_DECLINED, TRANSACTION_NOT_APPROVED ou FRAUDULENT. Dans ces cas, la banque ne communique pas la raison précise, et ni Dodo Payments ni le marchand ne peuvent annuler sa décision. Demandez au client de contacter sa banque pour résoudre le signalement, ou d’utiliser une autre carte ou un autre moyen de paiement.

​
Gestion programmatique des échecs

Lisez error_code depuis le webhook payment.failed ou l’objet de paiement, associez-le à l’action recommandée ci-dessus et déterminez s’il faut réessayer. Pour les renouvellements d’abonnement, les refus temporaires font automatiquement l’objet de nouvelles tentatives — consultez Subscription Payment Retries. Pour les erreurs au niveau de l’API et de la logique métier (telles que PAYMENT_NOT_SUCCEEDED ou REFUND_WINDOW_EXPIRED) qui ne sont pas des refus de carte, consultez la référence Error Codes.

​
Articles associés

Handle Payment Failures

Guide de bout en bout pour détecter, afficher et réessayer les paiements échoués.

Error Codes

Codes d’erreur de l’API et de la logique métier pour les échecs qui ne sont pas des refus.

Subscription Payment Retries

Nouvelles tentatives automatiques permettant de récupérer les refus temporaires lors des renouvellements d’abonnement.

Subscription Dunning

Séquences d’e-mails permettant de récupérer les refus définitifs en invitant le client à mettre à jour son moyen de paiement.

​
Support

Pour obtenir une aide supplémentaire concernant les échecs de transaction ou les problèmes d’intégration, contactez notre équipe support à l’adresse support@dodopayments.com.
Dernière modification le 8 août 2026