Échecs de transaction

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 — une raison d’échec standardisée issue du tableau ci-dessous.
error_message — une explication lisible par l’utilisateur.
retry_attempt — 0 pour le prélèvement initial, 1 ou plus pour chaque nouvelle tentative planifiée de renouvellement d’un abonnement.

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.

Handle Payment Failures

Guide développeur étape par étape pour lire ces codes depuis les webhooks et l’API, les présenter 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 nouveau.

Type de refus	Signification	Action à effectuer	Exemples
Refus temporaire	Temporaire ou corrigeable — la même carte peut être acceptée lors d’une tentative ultérieure ou une fois que le client a corrigé ses informations.	Vous pouvez effectuer une nouvelle tentative (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`
Refus définitif	Définitif — réessayer avec la même carte ne modifiera pas le résultat.	N’effectuez pas de nouvelle tentative avec 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 automatiquement cette distinction : les refus temporaires font l’objet de nouvelles tentatives via Nouvelles tentatives de paiement d’abonnement, tandis que les refus définitifs interrompent immédiatement la chaîne de tentatives et sont mieux gérés avec Relances d’abonnement.

Ne révélez jamais au client la véritable raison de STOLEN_CARD, LOST_CARD, PICKUP_CARD ou FRAUDULENT. La divulgation de ces informations pourrait alerter un fraudeur. 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 dans vos journaux internes.

Raisons des échecs de transaction

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.

Code d’échec	Type	Erreur utilisateur	Description	Action recommandée
`AUTHENTICATION_FAILURE`	Soft	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`	Soft	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`	Soft	Oui	Le délai du processus d’authentification a expiré	Demandez au client de réessayer et de terminer rapidement l’authentification
`CARD_DECLINED`	Soft	Non	La carte a été refusée par la banque émettrice 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`	Soft	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`	Soft	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`	Soft	Oui	Le client a annulé la transaction	Permettez au client de reprendre le checkout lorsqu’il sera prêt
`DO_NOT_HONOR`	Hard	Non	La banque émettrice a explicitement refusé la transaction (code ISO 8583 05 — ne pas honorer) ; les réseaux considèrent ce refus comme définitif	Demandez au client de contacter sa banque ; n’effectuez pas de nouvelle tentative avec la même carte
`EXPIRED_CARD`	Hard	Oui	La carte a expiré	Demandez au client d’utiliser une carte dont la date d’expiration est valide
`FRAUDULENT`	Hard	Oui	La transaction a été signalée comme potentiellement frauduleuse	Affichez au client un message de refus générique — ne révélez pas la raison. Demandez-lui d’utiliser une autre carte
`GENERIC_DECLINE`	Soft	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`	Soft	Oui	Le code CVC fourni était incorrect	Demandez au client de saisir à nouveau le CVC correct
`INCORRECT_NUMBER`	Soft	Oui	Le numéro de carte a été saisi incorrectement	Demandez au client de saisir à nouveau le numéro de carte correct
`INSUFFICIENT_FUNDS`	Soft	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`	Hard	Oui	Les informations du compte fournies sont invalides	Demandez au client de contacter sa banque ou d’utiliser une autre carte
`INVALID_AMOUNT`	Soft	Oui	Le montant de la transaction est invalide	Vérifiez le montant et les éventuelles limites d’achat avec le client
`INVALID_CARD_NUMBER`	Soft	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`	Soft	Oui	Les informations du titulaire de la carte sont invalides	Demandez au client de corriger le nom du titulaire
`INVALID_CVC`	Soft	Oui	Le format du CVC est invalide	Demandez au client de saisir à nouveau un CVC valide
`INVALID_EXPIRY_YEAR`	Soft	Oui	L’année d’expiration de la carte est invalide	Demandez au client de saisir une date d’expiration valide
`INVALID_PIN`	Soft	Oui	Le PIN fourni est incorrect	Demandez au client de saisir à nouveau le PIN correct
`INVALID_REQUEST`	Soft	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`	Soft	Oui	L’identifiant UPI fourni est invalide	Demandez au client de saisir un identifiant UPI valide
`LIMIT_EXCEEDED`	Soft	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`	Hard	Oui	Une carte de test a été utilisée en mode live	Utilisez une carte réelle — réessayer avec la carte de test échouera toujours en mode live
`LOST_CARD`	Hard	Oui	La carte a été déclarée perdue	Affichez au client un message de refus générique — ne révélez pas la raison. Demandez-lui d’utiliser une autre carte
`MANDATE_INVALID`	Soft	Oui	Le mandat de paiement est invalide	Demandez au client de configurer à nouveau le mandat de paiement
`MANDATE_REQUIRED`	Soft	Oui	Un mandat est requis pour cette transaction	Configurez un mandat et demandez au client de l’autoriser avant le prélèvement
`MANDATE_REQUIRED_SYSTEM`	Hard	Non	Le système exige un mandat pour ce type de transaction	Assurez-vous que le parcours de configuration du mandat est terminé avant le prélèvement
`NETWORK_ERROR`	Soft	Non	Une erreur réseau s’est produite pendant la transaction	Transitoire — réessayez le paiement après un court délai
`NETWORK_TIMEOUT`	Soft	Non	La demande réseau a dépassé le délai d’attente	Transitoire — réessayez le paiement après un court délai
`ORDER_ALREADY_EXISTS`	Soft	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`	Soft	Non	Échec de la création de la commande pour la transaction	Erreur transitoire ou système — réessayez le paiement ; contactez le support si le problème persiste
`PAYMENT_METHOD_PROVIDER_DECLINED`	Hard	Oui	Le prestataire du moyen de paiement a refusé la transaction	Demandez au client de contacter son prestataire ou d’utiliser un autre moyen de paiement
`PAYMENT_METHOD_UNSUPPORTED`	Hard	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`	Hard	Oui	La carte a été déclarée perdue ou volée et signalée pour récupération	Affichez au client un message de refus générique — ne révélez pas la raison. Demandez-lui d’utiliser une autre carte
`PROCESSING_ERROR`	Soft	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`	Hard	Non	Le prestataire de paiement ne prend pas en charge ce type de transaction	Demandez au client d’utiliser un autre moyen de paiement
`REENTER_TRANSACTION`	Soft	Oui	La transaction doit être saisie à nouveau	Demandez au client de réessayer le paiement
`REVOCATION_OF_AUTHORIZATION`	Hard	Oui	L’autorisation de la transaction a été révoquée	Demandez au client d’utiliser un autre moyen de paiement
`STOLEN_CARD`	Hard	Oui	La carte a été déclarée volée	Affichez au client un message de refus générique — ne révélez pas la raison. Demandez-lui d’utiliser une autre carte
`SUBSCRIPTION_NOT_ACTIVE`	Hard	Non	L’abonnement n’est pas actif ; le prélèvement 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 prélèvement
`TRANSACTION_NOT_ALLOWED`	Hard	Oui	La transaction n’est pas autorisée pour cette carte ou ce compte	Demandez au client de contacter sa banque pour autoriser ce type de transaction ou d’utiliser une autre carte
`TRANSACTION_NOT_APPROVED`	Hard	Oui	La transaction n’a pas été approuvée	Demandez au client de contacter sa banque ou d’essayer une autre carte
`TRY_AGAIN_LATER`	Soft	Non	La transaction doit faire l’objet d’une nouvelle tentative ultérieurement	Transitoire — réessayez le paiement plus tard
`UNKNOWN_ERROR`	Soft	Non	Une erreur inconnue s’est produite	Réessayez le paiement ; si le problème persiste, contactez le support

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 les informations correctes de sa 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.

Une carte peut également être refusée lorsque le moteur de gestion des risques de la banque émettrice signale le titulaire comme un client à haut risque, 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 passer outre cette 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 effectuer une nouvelle tentative. Pour les renouvellements d’abonnement, les refus temporaires font automatiquement l’objet de nouvelles tentatives pour vous — consultez Nouvelles tentatives de paiement 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 carte, consultez la référence Codes d’erreur.

Pages associées

Handle Payment Failures

Guide de bout en bout pour détecter, présenter 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 qui récupèrent les refus temporaires lors des renouvellements d’abonnement.

Subscription Dunning

Séquences d’e-mails qui récupèrent 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, veuillez contacter notre é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

Brands

Webhooks

Miscellaneous

Product Collections

Vue d’ensemble

Handle Payment Failures

Refus temporaires et définitifs

Raisons des échecs de transaction

Gestion programmatique des échecs

Pages associées

Handle Payment Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Support

​Vue d’ensemble

Handle Payment Failures

​Refus temporaires et définitifs

​Raisons des échecs de transaction

​Gestion programmatique des échecs

​Pages associées

Handle Payment Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

​Support

Vue d’ensemble

Refus temporaires et définitifs

Raisons des échecs de transaction

Gestion programmatique des échecs

Pages associées

Support