Échecs de transaction

Vue d’ensemble

Lorsqu’une tentative de paiement échoue, Dodo Payments renvoie un code d’échec standardisé qui vous indique pourquoi. Les codes sont les mêmes pour tous les moyens de paiement et processeurs de paiement. Un seul ensemble de règles de traitement couvre donc tous les paiements échoués. Le webhook payment.failed et l’objet de paiement exposent les champs suivants pour un paiement échoué :

error_code : un code d’échec standardisé du tableau ci-dessous.
error_message : une explication 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 la transaction d’origine, et 1 ou une valeur supérieure pour chaque nouvelle tentative de renouvellement d’abonnement planifiée. Les paiements qui ne sont pas des renouvellements d’abonnement conservent la valeur 0.

Utilisez ces codes pour fournir aux clients des indications claires, déterminer si une nouvelle tentative peut aboutir et récupérer davantage de revenus.

Texte destiné au marchand et texte destiné au client

Chaque code d’échec standardisé correspond à deux messages : un pour vous et un pour votre client :

Audience	Emplacement	Contenu
Vous	`error_message` sur le paiement, la page des détails du paiement dans le tableau de bord et l’e-mail d’échec de paiement reçu par les marchands	La véritable raison et une action recommandée, par exemple « La carte n’a pas été activée par son titulaire. Demandez au client de l’activer auprès de sa banque, puis réessayez. »
Votre client	L’écran d’échec du checkout, le Customer Portal et les e-mails de relance de paiement	Une explication courte et simple qu’il peut suivre, par exemple « Votre carte n’a pas encore été activée. Veuillez l’activer auprès de votre banque, puis réessayez. »

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. Le 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 correspond soit à un refus temporaire, soit à un refus définitif. Le type indique si une tentative ultérieure avec les mêmes informations de paiement peut aboutir ou si le client doit d’abord agir.

Type de refus	Signification	Action à effectuer	Exemples
Refus temporaire	Temporaire. Les mêmes informations de paiement peuvent aboutir lors d’une tentative ultérieure.	Réessayez après un délai.	`INSUFFICIENT_FUNDS`, `GENERIC_DECLINE`, `CARD_VELOCITY_EXCEEDED`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `NETWORK_TIMEOUT`, `TRY_AGAIN_LATER`
Refus définitif	Une nouvelle tentative avec les mêmes informations de paiement et sans action du client ne modifiera pas le résultat.	Ne réessayez pas avec les mêmes informations. Demandez au client de corriger ses informations, de terminer l’authentification, de contacter sa banque ou d’utiliser un autre moyen de paiement.	`STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`, `INCORRECT_CVC`

Pour les renouvellements d’abonnement, Dodo Payments applique automatiquement cette classification. Subscription Payment Retries effectue de nouvelles tentatives pour les refus temporaires. Un refus définitif met immédiatement fin à la chaîne de tentatives ; récupérez-le avec Subscription Dunning.

Ne révélez jamais au client la véritable raison correspondant à STOLEN_CARD, LOST_CARD, PICKUP_CARD ou FRAUDULENT. La divulgation de ces raisons peut alerter un acteur frauduleux. Affichez 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 enregistrez le code spécifique uniquement en interne.Dodo Payments applique 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 affichent un message de refus générique, tandis que votre texte destiné au marchand 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 avec son type de refus, la possibilité pour le client de le résoudre, une description et l’action recommandée.

Code d’échec	Type	Erreur utilisateur	Description	Action recommandée
`AUTHENTICATION_FAILURE`	Définitif	Oui	L’authentification a échoué pendant la transaction	Demandez au client de réessayer et de terminer l’authentification 3DS, ou d’utiliser une autre carte
`AUTHENTICATION_REQUIRED`	Définitif	Oui	Une authentification supplémentaire est nécessaire pour terminer la transaction	Invitez le client à terminer l’authentification 3DS. Pour les renouvellements d’abonnement, demandez-lui de revenir et de s’authentifier
`AUTHENTICATION_TIMEOUT`	Temporaire	Oui	Le délai du processus d’authentification a expiré	Demandez au client de réessayer et de terminer rapidement l’authentification
`CARD_DECLINED`	Temporaire	Non	La banque émettrice a refusé la carte sans raison précise (refus générique)	Demandez au client de réessayer, de contacter sa banque ou d’utiliser une autre carte
`CARD_NOT_ACTIVATED`	Temporaire	Oui	Le titulaire n’a pas activé la carte	Demandez au client d’activer la carte auprès de sa banque, puis de réessayer
`CARD_VELOCITY_EXCEEDED`	Temporaire	Oui	Trop de transactions ont été tentées sur une courte période	Demandez au client d’attendre et de réessayer plus tard, ou de contacter sa banque au sujet des limites
`CUSTOMER_CANCELLED`	Définitif	Oui	Le client a annulé la transaction	Laissez le client recommencer le checkout lorsqu’il sera prêt
`DO_NOT_HONOR`	Définitif	Non	La banque émettrice a explicitement refusé la transaction (code ISO 8583 05, ne pas honorer). Les réseaux de cartes considèrent ce refus comme définitif	Demandez au client de contacter sa banque. Ne réessayez pas avec la même carte
`EXPIRED_CARD`	Définitif	Oui	La carte a expiré	Demandez au client d’utiliser une carte dont la date d’expiration est valide
`FRAUDULENT`	Définitif	Oui	La transaction a été signalée comme potentiellement frauduleuse	Affichez au client un message de refus générique, sans en indiquer la raison. Demandez-lui d’utiliser une autre carte
`GENERIC_DECLINE`	Temporaire	Non	La transaction a été refusée pour une raison non précisée	Demandez au client de contacter sa banque ou d’essayer une autre carte
`INCORRECT_CVC`	Définitif	Oui	Le CVC saisi est incorrect	Demandez au client de saisir à nouveau le CVC correct
`INCORRECT_NUMBER`	Définitif	Oui	Le numéro de carte a été saisi incorrectement	Demandez au client de saisir à nouveau le numéro de carte correct
`INSUFFICIENT_FUNDS`	Temporaire	Oui	Le compte ne dispose pas de fonds suffisants pour terminer la transaction	Demandez au client d’utiliser un autre moyen de paiement ou de réessayer lorsque les fonds seront disponibles
`INVALID_ACCOUNT`	Définitif	Oui	Les informations du compte fournies sont invalides	Demandez au client de contacter sa banque ou d’utiliser une autre carte
`INVALID_AMOUNT`	Définitif	Oui	Le montant de la transaction est invalide	Vérifiez le montant et les éventuelles limites d’achat avec le client
`INVALID_CARD_NUMBER`	Définitif	Oui	Le format du numéro de carte est invalide	Demandez au client de saisir à nouveau un numéro de carte valide
`INVALID_CARD_OWNER`	Définitif	Oui	Les informations du titulaire de la carte sont invalides	Demandez au client de corriger le nom du titulaire de la carte
`INVALID_CVC`	Définitif	Oui	Le format du CVC est invalide	Demandez au client de saisir à nouveau un CVC valide
`INVALID_EXPIRY_YEAR`	Définitif	Oui	L’année d’expiration de la carte est invalide	Demandez au client de saisir une date d’expiration valide
`INVALID_PIN`	Définitif	Oui	Le PIN saisi est incorrect	Demandez au client de saisir à nouveau le PIN correct
`INVALID_REQUEST`	Définitif	Oui	La demande de transaction contient des données invalides	Vérifiez les champs de la demande de paiement et renvoyez-la avec des données valides
`INVALID_UPI_ID`	Définitif	Oui	L’identifiant UPI fourni est invalide	Demandez au client de saisir un identifiant UPI valide
`LIMIT_EXCEEDED`	Temporaire	Oui	La transaction dépasse la limite de la carte ou du compte	Demandez au client de contacter sa banque au sujet des limites ou d’utiliser un autre moyen de paiement
`LIVE_MODE_TEST_CARD`	Définitif	Oui	Une carte de test a été utilisée en mode live	Utilisez une vraie carte. Une carte de test échoue toujours en mode live
`LOST_CARD`	Définitif	Oui	La carte a été signalée comme perdue	Affichez au client un message de refus générique, sans en indiquer la raison. Demandez-lui d’utiliser une autre carte
`MANDATE_INVALID`	Définitif	Oui	Le mandat de paiement est invalide	Demandez au client de configurer à nouveau le mandat de paiement
`MANDATE_REQUIRED`	Définitif	Oui	Un mandat est requis pour cette transaction	Configurez un mandat et demandez au client de l’autoriser avant le débit
`MANDATE_REQUIRED_SYSTEM`	Définitif	Non	Le système exige un mandat pour ce type de transaction	Terminez le parcours de configuration du mandat avant le débit
`NETWORK_ERROR`	Temporaire	Non	Une erreur réseau s’est produite pendant la transaction	Transitoire. Réessayez le paiement après un court délai
`NETWORK_TIMEOUT`	Temporaire	Non	La demande réseau a expiré	Transitoire. Réessayez le paiement après un court délai
`ORDER_ALREADY_EXISTS`	Définitif	Non	Une commande existe déjà pour cette transaction (création d’une commande en double)	Vérifiez l’état de la commande existante avant de réessayer. Contactez le support si le problème persiste
`ORDER_CREATION_FAILED`	Temporaire	Non	La commande correspondant à la transaction n’a pas pu être créée	Erreur transitoire ou système. Réessayez le paiement et contactez le support si le problème persiste
`PAYMENT_METHOD_PROVIDER_DECLINED`	Définitif	Oui	Le fournisseur du moyen de paiement a refusé la transaction	Demandez au client de contacter son fournisseur ou d’utiliser un autre moyen de paiement
`PAYMENT_METHOD_UNSUPPORTED`	Définitif	Oui	Le moyen de paiement n’est pas pris en charge pour cette transaction	Demandez au client d’utiliser un moyen de paiement pris en charge
`PICKUP_CARD`	Définitif	Oui	La carte a été signalée comme perdue ou volée et marquée pour récupération	Affichez au client un message de refus générique, sans en indiquer la raison. Demandez-lui d’utiliser une autre carte
`PROCESSING_ERROR`	Temporaire	Non	Une erreur s’est produite lors du traitement de la transaction	Transitoire. Réessayez le paiement. Si le problème persiste, demandez au client de contacter sa banque
`PROVIDER_UNSUPPORTED`	Définitif	Non	Le fournisseur de paiement ne prend pas en charge ce type de transaction	Demandez au client d’utiliser un autre moyen de paiement
`REENTER_TRANSACTION`	Temporaire	Oui	La transaction doit être saisie à nouveau	Demandez au client de réessayer le paiement
`REVOCATION_OF_AUTHORIZATION`	Définitif	Oui	L’autorisation de la transaction a été révoquée	Demandez au client d’utiliser un autre moyen de paiement
`STOLEN_CARD`	Définitif	Oui	La carte a été signalée comme volée	Affichez au client un message de refus générique, sans en indiquer la raison. Demandez-lui d’utiliser une autre carte
`SUBSCRIPTION_NOT_ACTIVE`	Définitif	Non	L’abonnement n’est pas actif, et le débit récurrent n’a donc pas pu être traité	Réactivez l’abonnement (par exemple, en mettant à jour le moyen de paiement) avant de tenter à nouveau le débit
`TRANSACTION_NOT_ALLOWED`	Temporaire	Oui	La transaction n’est pas autorisée pour cette carte ou ce compte	Réessayez après un délai. Si l’échec persiste, demandez au client de contacter sa banque pour autoriser ce type de transaction ou d’utiliser une autre carte
`TRANSACTION_NOT_APPROVED`	Temporaire	Oui	La transaction n’a pas été approuvée	Réessayez après un délai. Si l’échec persiste, demandez au client de contacter sa banque ou d’essayer une autre carte
`TRY_AGAIN_LATER`	Temporaire	Non	La transaction doit être réessayée ultérieurement	Transitoire. Réessayez le paiement plus tard
`UNKNOWN_ERROR`	Temporaire	Non	Une erreur inconnue s’est produite	Réessayez le paiement. Si le problème persiste, contactez le support

User Error indique si le client peut résoudre le refus. Yes signifie que le client peut corriger le problème, par exemple en saisissant les informations correctes de sa carte. No signifie qu’un problème au niveau du système ou une restriction bancaire a provoqué le refus et que le client ne peut pas le résoudre directement.

Une banque émettrice peut également refuser une carte parce que son propre moteur de gestion des risques signale le titulaire de la carte comme présentant un risque élevé, indépendamment du marchand ou des détails de la transaction. Ces refus apparaissent généralement sous forme de codes génériques tels que DO_NOT_HONOR, GENERIC_DECLINE, CARD_DECLINED, TRANSACTION_NOT_APPROVED ou FRAUDULENT. La banque ne communique pas la raison précise, et ni Dodo Payments ni le marchand ne peuvent passer outre cette décision. Demandez au client de contacter sa banque pour résoudre ce problème, 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 dans le tableau et déterminez s’il faut réessayer. Pour les renouvellements d’abonnement, Dodo Payments réessaie les refus temporaires pour vous. Consultez Subscription Payment Retries. Pour les erreurs d’API et de logique métier qui ne sont pas des refus de carte, telles que PAYMENT_NOT_SUCCEEDED ou REFUND_WINDOW_EXPIRED, 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 davantage d’aide concernant les échecs de transaction ou les problèmes d’intégration, contactez l’équipe de support à l’adresse support@dodopayments.com.

API Reference

Checkout Sessions

Payments

Subscriptions

Discounts

Licenses

Entitlements

Customers

Customer Wallets

Products

Localized Pricing

Addons

Credit Entitlements

Meters

Usage Events

Refunds

Disputes

Payouts

Balance Ledger

Moderation

Brands

Webhooks

Miscellaneous

Product Collections

Vue d’ensemble

Texte destiné au marchand et texte destiné au client

Handle Payment Failures

Refus temporaires et définitifs

Motifs d’échec des transactions

Gestion programmatique des échecs

Articles associés

Handle Payment Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Support

​Vue d’ensemble

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

Handle Payment Failures

​Refus temporaires et définitifs

​Motifs d’échec des transactions

​Gestion programmatique des échecs

​Articles associés

Handle Payment Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

​Support

Vue d’ensemble

Texte destiné au marchand et texte destiné au client

Refus temporaires et définitifs

Motifs d’échec des transactions

Gestion programmatique des échecs

Articles associés

Support