Passer au contenu principal

​
Aperçu

Dodo Payments renvoie une raison détaillée d’échec chaque fois qu’une tentative de paiement échoue. Ces raisons sont standardisées entre les méthodes de paiement et les fournisseurs, vous permettant de mettre en place une gestion cohérente dans votre application. Lorsqu’un paiement échoue, le webhook payment.failed et l’objet de paiement exposent :
  • error_code — une raison d’échec standardisée du tableau ci-dessous.
  • error_message — une explication lisible par l’homme.
  • retry_attempt — 0 pour le prélèvement initial, 1 ou plus pour chaque tentative de renouvellement d’abonnement planifiée.
Comprendre ces raisons d’échec vous permet de donner un retour clair aux clients, de décider si une nouvelle tentative est justifiée, et de récupérer plus de revenus. A step-by-step developer guide for reading these codes from webhooks and the API, surfacing them to customers, and deciding when to retry.

​
Rejets soft vs. hard

Chaque code d’échec appartient à l’une des deux catégories. Cette distinction détermine si vous devez réessayer la même méthode de paiement ou demander au client d’en fournir une nouvelle.
Type de rejetCe que cela signifieQue faireExemples
Rejet softTemporaire ou corrigible — la même carte peut réussir lors d’une tentative ultérieure ou une fois que le client corrige ses informations.Sans risque de réessayer (après un délai, ou une fois que le client a corrigé ses informations).INSUFFICIENT_FUNDS, GENERIC_DECLINE, CARD_VELOCITY_EXCEEDED, PROCESSING_ERROR, NETWORK_ERROR, NETWORK_TIMEOUT, TRY_AGAIN_LATER
Rejet hardTerminal — réessayer la même carte ne changera pas le résultat.Ne pas réessayer la même carte. Demandez au client d’utiliser un autre moyen de paiement ou de contacter sa banque.STOLEN_CARD, LOST_CARD, PICKUP_CARD, DO_NOT_HONOR, FRAUDULENT, INVALID_ACCOUNT
Pour les renouvellements d’abonnement, Dodo Payments applique cette distinction automatiquement : les rejets soft sont réessayés par réessai de paiements d’abonnement, tandis que les rejets hard mettent fin immédiatement à la chaîne de tentatives et sont mieux traités avec recouvrement des abonnements. Ne jamais révéler la véritable raison pour STOLEN_CARD, LOST_CARD, PICKUP_CARD, ou FRAUDULENT au client. Révéler ces informations peut avertir un acteur frauduleux. Montrez toujours un message de refus générique au client (par exemple, « Votre carte a été refusée. Veuillez contacter votre banque ou utiliser une autre carte. ») et enregistrez uniquement le code spécifique en interne.

​
Raisons d’échec des transactions

Le tableau suivant liste chaque code d’échec, son type de refus, si le client peut le résoudre, une description, et l’action recommandée.
Code d’échecTypeErreur utilisateurDescriptionAction recommandée
AUTHENTICATION_FAILURESoftOuiÉchec de l’authentification lors de la transactionDemandez au client de réessayer et de compléter l’authentification 3DS, ou d’utiliser une autre carte
AUTHENTICATION_REQUIREDSoftOuiUne authentification supplémentaire est nécessaire pour compléter la transactionInvitez le client à compléter l’authentification 3DS. Pour les renouvellements d’abonnement, demandez au client de revenir et de s’authentifier
AUTHENTICATION_TIMEOUTSoftOuiLe processus d’authentification a expiréDemandez au client de réessayer et de compléter l’authentification rapidement
CARD_DECLINEDSoftNonLa carte a été refusée par la banque émettrice sans raison spécifique (refus générique)Demandez au client de réessayer, de contacter sa banque, ou d’utiliser une autre carte
CARD_NOT_ACTIVATEDSoftOuiLa carte n’a pas été activée par le titulaireDemandez au client d’activer la carte auprès de sa banque, puis de réessayer
CARD_VELOCITY_EXCEEDEDSoftOuiTrop de transactions tentées dans un court laps de tempsDemandez au client d’attendre et de réessayer plus tard, ou de contacter sa banque au sujet des limites
CUSTOMER_CANCELLEDSoftOuiLe client a annulé la transactionLaissez le client redémarrer le paiement lorsqu’il est prêt
DO_NOT_HONORHardNonLa banque émettrice a explicitement refusé la transaction (code ISO 8583 05 — ne pas honorer); les réseaux le traitent comme terminalDemandez au client de contacter sa banque; ne pas réessayer la même carte
EXPIRED_CARDHardOuiLa carte a expiréDemandez au client d’utiliser une carte avec une date d’expiration valide
FRAUDULENTHardOuiLa transaction a été signalée comme potentiellement frauduleuseMontrez un message de refus générique au client — ne pas révéler la raison. Demandez-lui d’utiliser une autre carte
GENERIC_DECLINESoftNonLa transaction a été refusée pour une raison non spécifiéeDemandez au client de contacter sa banque ou d’essayer une autre carte
INCORRECT_CVCSoftOuiLe code CVC fourni était incorrectDemandez au client de saisir à nouveau le code CVC correct
INCORRECT_NUMBERSoftOuiLe numéro de carte a été saisi incorrectementDemandez au client de saisir à nouveau le numéro de carte correct
INSUFFICIENT_FUNDSSoftOuiLe compte a des fonds insuffisants pour compléter la transactionDemandez au client d’utiliser un autre moyen de paiement ou de réessayer lorsque les fonds sont disponibles
INVALID_ACCOUNTHardOuiLes informations de compte fournies sont invalidesDemandez au client de contacter sa banque ou d’utiliser une autre carte
INVALID_AMOUNTSoftOuiLe montant de la transaction est invalideVérifiez le montant et toute limite d’achat avec le client
INVALID_CARD_NUMBERSoftOuiLe format du numéro de carte est invalideDemandez au client de saisir à nouveau un numéro de carte valide
INVALID_CARD_OWNERSoftOuiLes informations sur le propriétaire de la carte sont invalidesDemandez au client de corriger le nom du titulaire de la carte
INVALID_CVCSoftOuiLe format du CVC est invalideDemandez au client de saisir à nouveau un CVC valide
INVALID_EXPIRY_YEARSoftOuiL’année d’expiration de la carte est invalideDemandez au client de saisir une date d’expiration valide
INVALID_PINSoftOuiLe code PIN fourni est incorrectDemandez au client de saisir à nouveau le code PIN correct
INVALID_REQUESTSoftOuiLa demande de transaction contient des données invalidesVérifiez les champs de la demande de paiement et soumettez à nouveau avec des données valides
INVALID_UPI_IDSoftOuiL’identifiant UPI fourni est invalideDemandez au client de saisir un identifiant UPI valide
LIMIT_EXCEEDEDSoftOuiLa transaction dépasse la limite de la carte ou du compteDemandez au client de contacter sa banque au sujet des limites, ou d’utiliser une autre méthode
LIVE_MODE_TEST_CARDHardOuiUne carte de test a été utilisée en mode liveUtilisez une vraie carte — réessayer la carte de test échouera toujours en mode live
LOST_CARDHardOuiLa carte a été signalée comme perdueMontrez un message de refus générique au client — ne pas révéler la raison. Demandez-lui d’utiliser une autre carte
MANDATE_INVALIDSoftOuiLe mandat de paiement est invalideDemandez au client de configurer à nouveau le mandat de paiement
MANDATE_REQUIREDSoftOuiUn mandat est requis pour cette transactionConfigurez un mandat et demandez au client de l’autoriser avant de facturer
MANDATE_REQUIRED_SYSTEMHardNonLe système nécessite un mandat pour ce type de transactionAssurez-vous que le processus de configuration du mandat est terminé avant de facturer
NETWORK_ERRORSoftNonUne erreur réseau s’est produite lors de la transactionTransitoire — réessayez le paiement après un court délai
NETWORK_TIMEOUTSoftNonLa demande réseau a expiréTransitoire — réessayez le paiement après un court délai
ORDER_ALREADY_EXISTSSoftNonUne commande existe déjà pour cette transaction (création de commande en double)Vérifiez le statut de la commande existante avant de réessayer ; contactez le support si cela persiste
ORDER_CREATION_FAILEDSoftNonÉchec de la création de la commande pour la transactionErreur transitoire/système — réessayez le paiement ; contactez le support si cela persiste
PAYMENT_METHOD_PROVIDER_DECLINEDHardOuiLe fournisseur de méthode de paiement a refusé la transactionDemandez au client de contacter son fournisseur ou d’utiliser une autre méthode de paiement
PAYMENT_METHOD_UNSUPPORTEDHardOuiLa méthode de paiement n’est pas supportée pour cette transactionDemandez au client d’utiliser une méthode de paiement supportée
PICKUP_CARDHardOuiLa carte a été signalée comme perdue ou volée et marquée pour récupérationMontrez un message de refus générique au client — ne pas révéler la raison. Demandez-lui d’utiliser une autre carte
PROCESSING_ERRORSoftNonUne erreur s’est produite lors du traitement de la transactionTransitoire — réessayez le paiement ; si cela persiste, demandez au client de contacter sa banque
PROVIDER_UNSUPPORTEDHardNonLe fournisseur de paiement ne supporte pas ce type de transactionDemandez au client d’utiliser une autre méthode de paiement
REENTER_TRANSACTIONSoftOuiLa transaction doit être ressaisieDemandez au client de réessayer le paiement
REVOCATION_OF_AUTHORIZATIONHardOuiL’autorisation de la transaction a été révoquéeDemandez au client d’utiliser une autre méthode de paiement
STOLEN_CARDHardOuiLa carte a été signalée comme voléeMontrez un message de refus générique au client — ne pas révéler la raison. Demandez-lui d’utiliser une autre carte
SUBSCRIPTION_NOT_ACTIVEHardNonL’abonnement n’est pas actif, donc la charge récurrente n’a pas pu être traitéeRéactivez l’abonnement (par exemple, en mettant à jour le moyen de paiement) avant de tenter à nouveau la charge
TRANSACTION_NOT_ALLOWEDHardOuiLa transaction n’est pas autorisée pour cette carte ou ce compteDemandez au client de contacter sa banque pour autoriser ce type de transaction, ou d’utiliser une autre carte
TRANSACTION_NOT_APPROVEDHardOuiLa transaction n’a pas été approuvéeDemandez au client de contacter sa banque ou d’essayer une autre carte
TRY_AGAIN_LATERSoftNonLa transaction doit être réessayée plus tardTransitoire — réessayez le paiement plus tard
UNKNOWN_ERRORSoftNonUne erreur inconnue s’est produiteRéessayez le paiement ; si cela persiste, contactez le support
Erreur utilisateur indique si le refus de paiement peut être résolu par le client. Lorsque Yes, le client peut prendre des mesures pour résoudre le problème (par exemple, saisir les détails corrects de la carte). Lorsque No, le refus est dû à des problèmes au niveau du système ou à des restrictions bancaires que le client ne peut pas résoudre directement.

​
Gestion des échecs de manière programmatique

Lisez error_code à partir du webhook payment.failed ou de l’objet de paiement, mappez-le à l’action recommandée ci-dessus, et décidez si vous devez réessayer. Pour les renouvellements d’abonnement, les rejets soft sont automatiquement réessayés pour vous — voir Réessai de paiements d’abonnement. 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 cartes, consultez la référence des codes d’erreur. End-to-end guide to detecting, surfacing, and retrying failed payments. API and business-logic error codes for non-decline failures. Automatic retries that recover soft declines on subscription renewals. Email sequences that recover hard declines by prompting a payment method update.

​
Support

Pour une aide supplémentaire concernant les échecs de transaction ou les problèmes d’intégration, veuillez contacter notre équipe de support à support@dodopayments.com.
Dernière modification le 18 juin 2026