Chargement de vos clés API…

Codes de refus

Pourquoi un paiement carte a été refusé, et quoi afficher à votre client.

Ne confondez pas erreur d'API et refus de paiement

Une erreur d'API signale que votre requête n'a pas pu être traitée (champ manquant, clé invalide). Un refus signale que la requête était correcte mais que la banque du porteur n'a pas autorisé le paiement. Dans ce cas, le paiement existe bel et bien dans votre compte, avec le statut failed, et porte son motif.

Un débit direct refusé répond HTTP 402, jamais 201 : un intégrateur qui ne lit que le code HTTP ne peut donc pas confondre un refus avec un encaissement.

{
  "paymentId": "pay_3f9c2a1b7d4e5f60",
  "status": "failed",
  "monextTransactionId": "17216221653707",
  "failureCode": "01902",
  "failureReason": "La banque n'a pas pu traiter la transaction, réessayez",
  "settlement": null,
  "platformDistribution": null
}

Où récupérer le motif

Réponse 402 de POST /payment/directDebit et de la capture.
Webhook payment.failed, pour le traitement asynchrone de la commande.
GET /payment/{paymentId}, pour un affichage différé ou une demande d'assistance.
Votre espace marchand, colonne « Motif » du détail de la transaction.

Si vous utilisez la page de paiement Mobupay, le motif est déjà affiché au client : vous n'avez rien à faire. Le code technique n'est jamais placé dans l'URL de retour, récupérez-le par webhook.

Familles de motifs

Chaque code appartient à une famille, qui suffit à décider de la marche à suivre. Un code inconnu de cette page reste toujours classé, jamais masqué.

Famille	Conduite à tenir
Plafond	Une limite du porteur est atteinte : montant, fréquence ou nombre d'utilisations. Un nouvel essai plus tard, ou avec une autre carte, peut aboutir.
Banque	Refus de l'émetteur, souvent sans motif communiqué. Le client doit contacter sa banque ou utiliser une autre carte.
Authentification	Le parcours 3-D Secure n'a pas abouti. Invitez le client à recommencer en validant la demande de sa banque.
Technique	Incident de l'acquéreur ou du serveur bancaire, ou erreur de configuration. La carte n'est pas en cause : un nouvel essai a de bonnes chances d'aboutir.
Fraude	Usage frauduleux soupçonné. Ne relancez pas le paiement, la banque a bloqué la carte.
Carte	La carte elle-même est en cause : expirée, inactive, perdue, volée ou non acceptée. Le client doit en utiliser une autre.
Session	Le paiement n'a pas été mené à son terme (abandon, expiration, doublon). Vous pouvez renvoyer un lien de paiement.

Tous les codes

La colonne « Motif » est exactement la chaîne renvoyée dans failureReason : elle est rédigée pour être affichée telle quelle à votre client.

Code	Motif renvoyé	Famille	Réessai
01100	Paiement refusé par la banque, sans motif communiqué	Banque	autre carte
01101	Carte expirée	Carte	autre carte
01103	Refus : contactez votre banque	Banque	autre carte
01108	Refus : contactez votre banque	Banque	autre carte
01109	Contrat marchand non reconnu par la banque	Technique	non
01110	Montant invalide pour la banque	Technique	après correction
01111	Numéro de carte invalide	Carte	après correction
01113	Paiement refusé par la banque	Banque	autre carte
01114	Compte bancaire inexistant	Banque	autre carte
01115	Opération non prise en charge par la banque	Technique	non
01116	Plafond de la carte dépassé	Plafond	oui
01117	Code confidentiel incorrect	Banque	après correction
01118	Carte non enregistrée chez l'émetteur	Carte	autre carte
01119	Paiement non autorisé pour cette carte	Banque	autre carte
01120	Paiement refusé par le terminal	Banque	autre carte
01121	Retrait ou paiement au-delà du plafond autorisé	Plafond	oui
01122	Refus pour raison de sécurité	Fraude	non
01123	Nombre d'opérations autorisées dépassé	Plafond	oui
01125	Carte inactive	Carte	autre carte
01126	Format du code confidentiel invalide	Banque	après correction
01128	Erreur de contrôle du code confidentiel	Banque	autre carte
01129	Carte suspectée contrefaite	Fraude	non
01130	Cryptogramme visuel (CVV) incorrect	Banque	après correction
01131	Authentification 3-D Secure exigée par la banque	Authentification	oui
01132	Paiement récurrent révoqué par le porteur	Banque	non
01133	Tous les paiements sur cette carte ont été révoqués par le porteur	Banque	non
01151	Code confidentiel incorrect	Banque	après correction
01180	Banque inconnue	Technique	non
01181	Devise non acceptée par la banque	Technique	non
01182	Taux de conversion introuvable	Technique	oui
01183	Montant maximal autorisé dépassé	Plafond	oui
01184	Nombre d'utilisations maximal atteint	Plafond	oui
01185	Commande déjà utilisée	Technique	non
01196	Réponse incomplète du serveur bancaire, réessayez	Technique	oui
01197	Communication avec l'acquéreur interrompue, réessayez	Technique	oui
01198	Erreur de configuration chez l'acquéreur	Technique	non
01199	Erreur interne du système bancaire, réessayez	Technique	oui
01200	Paiement refusé par la banque	Banque	autre carte
01201	Carte expirée	Carte	autre carte
01202	Paiement refusé par la banque (suspicion de fraude)	Fraude	non
01203	Refus : contactez votre banque	Banque	autre carte
01204	Carte restreinte	Banque	non
01205	Paiement refusé par la banque	Banque	autre carte
01206	Nombre maximal de tentatives atteint	Banque	non
01207	Refus de la banque	Banque	autre carte
01208	Carte déclarée perdue	Carte	non
01209	Carte déclarée volée	Carte	non
01214	Provision insuffisante sur le compte	Banque	oui
01280	Type de carte non accepté	Carte	autre carte
01902	La banque n'a pas pu traiter la transaction, réessayez	Technique	oui
01904	Demande refusée par la banque pour un problème de format	Technique	oui
01907	Serveur de la banque émettrice en erreur, réessayez	Technique	oui
01909	Erreur interne du serveur bancaire, réessayez	Technique	oui
01911	Émetteur de la carte injoignable, réessayez	Technique	oui
01912	Erreur interne du serveur de l'émetteur, réessayez	Technique	oui
01913	Transaction en double	Technique	non
01914	Transaction introuvable chez la banque	Technique	oui
01915	Opération annulée : action non autorisée	Technique	non
01917	Cette transaction ne peut pas être rejouée	Technique	non
01940	Serveur de la banque indisponible, réessayez	Technique	oui
01941	Communication avec le serveur bancaire interrompue, réessayez	Technique	oui
01942	Erreur interne du serveur bancaire, réessayez	Technique	oui
01943	Erreur interne du serveur bancaire, réessayez	Technique	oui
02001	Transaction en double	Session	non
02008	Paiement annulé par le client	Session	oui
02103	Délai de connexion dépassé, réessayez	Session	oui
02305	Paiement en cours de traitement	Session	non
02306	Paiement non finalisé (session encore en cours)	Session	oui
02324	Session de paiement expirée	Session	oui
03003	Erreur acquéreur, réessayez plus tard	Banque	oui
03004	Paiement refusé par la banque	Banque	autre carte
03022	Échec de l'authentification 3-D Secure	Authentification	oui
03023	Authentification 3-D Secure abandonnée par le client	Authentification	oui

« Réessai » indique si relancer le même paiement a une chance d'aboutir : « oui » plus tard, « autre carte » avec un autre moyen de paiement, « après correction » une fois la saisie reprise par le client, « non » si la banque a bloqué la carte ou l'opération.

Codes non répertoriés

Un code absent de cette table reçoit un motif déduit de son préfixe, et vous est toujours transmis tel quel dans failureCode.

Préfixe	Signification
01xxx	Réponse de la banque du porteur ou de l'acquéreur.
019xx	Incident technique de l'acquéreur ou du serveur bancaire, jamais un refus de la carte.
02xxx	Parcours de paiement non abouti : abandon, expiration, doublon.
03xxx	Acquéreur et authentification du porteur.
04xxx	Carte refusée.
05xxx	Refus bancaire.

Bonnes pratiques

Affichez failureReason tel quel : c'est la chaîne que nous tenons à jour au fil des codes rencontrés.
Branchez votre logique sur failureCode, jamais sur le texte du motif, qui peut être reformulé.
N'affichez jamais un message d'une autre étape de votre tunnel : un refus bancaire annoncé comme un problème de formulaire fait renoncer un client qui aurait pu payer.
Ne relancez pas automatiquement un paiement refusé pour fraude, carte perdue ou volée.
Pour tester : la page cartes de test permet de provoquer un refus au centime près.