Gestion des erreurs
Capturez et répondez aux refus de paiement, aux données non valides, aux problèmes de réseau et plus.
Stripe présente plusieurs types d’erreurs, qui peuvent désigner des événements extérieurs, tels que des refus de paiement et des interruptions réseau, ou bien des problèmes de code, comme des appels à l’API non valides.
Utilisez certaines ou toutes les techniques présentées dans le tableau ci-dessous afin de traiter les erreurs. Peu importe la technique utilisée, vous pouvez poursuivre avec nos réponses recommandées pour chaque type d’erreur.
Technique | Objectif | Nécessaire |
---|---|---|
Utiliser les valeurs d’erreur | Rectifier les problèmes en cas d’interruption d’un appel à l’API | Systématiquement |
Surveiller les webhooks | Réagir aux notifications de Stripe | Parfois |
Obtenir des informations enregistrées sur les échecs | Analyser les problèmes passés et prendre en charge d’autres techniques | Parfois |
Utiliser des valeurs d’erreur
Les appels à l’API dans la bibliothèque Go de Stripe retournent une valeur de résultat et une valeur d’erreur. Utilisez des attributions multiples pour capturer ces deux valeurs. Si la valeur d’erreur n’est pas nil
, cela signifie qu’un problème immédiat a empêché la poursuite de l’appel à l’API.
Si la valeur de l’erreur concerne Stripe, vous pouvez la convertir en objet stripe.
qui contient des champs décrivant le problème. Utilisez le champ Type pour choisir une réponse. Dans certains cas, vous pouvez convertir la propriété Err
en un type d’erreur plus spécifique avec des informations complémentaires.
Une fois que vous avez configuré la manière de gérer les exceptions, effectuez des tests sur divers types de données, y compris des cartes de test, afin de simuler différents résultats de paiement.
Surveiller les webhooks
En cas de problème, Stripe vous avertit à l’aide de webhooks, y compris pour les problèmes qui ne surviennent pas immédiatement après un appel à l’API. Par exemple :
- Vous perdez un litige.
- Un paiement récurrent échoue après plusieurs mois sans souci.
- Votre front-end confirme un paiement, mais passe hors ligne avant l’échec du paiement. (Le back-end reçoit quand même une notification de webhook, même s’il n’a pas effectué l’appel à l’API.)
Il n’est pas nécessaire de traiter tous les types d’événements webhook. En réalité, certaines intégrations n’en traitent aucun.
Dans votre gestionnaire de webhooks, commencez par suivre les étapes de base de l’outil de création de webhook : prenez un objet Event et servez-vous du type d’événement pour découvrir ce qui s’est passé. Ensuite, si le type d’événement indique une erreur, suivez ces étapes supplémentaires :
- Récupérez l’objet concerné en désérialisant les données de
event.
.Data. Raw - Utilisez les informations stockées dans l’objet concerné pour obtenir des explications, y compris dans le cas d’un objet Error.
- Référez-vous au type de l’objet pour déterminer la marche à suivre.
Pour tester la réponse de votre intégration aux événements webhook, vous pouvez déclencher des événements webhook localement. Après avoir terminé les étapes de configuration sur ce lien, déclenchez un échec de paiement pour voir le message d’erreur qui en résulte.
stripe trigger payment_intent.payment_failed
A payment error occurred: Your card was declined.
Obtenir des informations enregistrées sur les échecs
De nombreux objets stockent des informations sur les échecs. Cela signifie que s’il y a déjà eu un problème, vous êtes en mesure de récupérer l’objet et de l’examiner afin d’en savoir plus. Les informations stockées se présentent généralement sous la forme d’un objet Error, et vous pouvez vous référer à sa classe pour déterminer la marche à suivre.
Par exemple :
- Récupérez un PaymentIntent spécifique.
- Vérifiez s’il y a eu une erreur de paiement en déterminant si l’objet last_payment_error est vide.
- Si c’est le cas, consignez l’erreur en incluant son type et l’objet concerné.
Voici quelques objets courants qui stockent des informations sur les échecs.
Objet | Attribut | Valeurs |
---|---|---|
Payment Intents | last_ | Un objet Error |
Setup Intents | last_ | Un objet Error |
Invoice | last_ | Un objet Error |
Setup Attempt | setup_ | Un objet Error |
Virement | failure_ | Un code d’échec de virement |
Refund | failure_ | Un code d’échec de remboursement |
Pour tester un code qui exploite des informations enregistrées à propos des échecs, vous serez parfois amené à simuler des échecs de transactions. Pour cela, utilisez des cartes de test ou des numéros de comptes bancaires de test. Par exemple :
- Simuler un refus de paiement pour générer des échecs de Charges, PaymentIntents, SetupIntents et autres.
- Simuler un échec de virement.
- Simuler un échec de remboursement.
Types d’erreurs et réponses
Dans la bibliothèque Go de Stripe, chaque objet Error possède un attribut Type
. Référez-vous à la documentation concernant chaque classe pour obtenir des conseils quant aux réponses à apporter.
Nom | Type | Description |
---|---|---|
Erreur de paiement | Une erreur est survenue lors d’un paiement. Voici les cas possibles : | |
Erreur de requête non valide | L’appel à l’API que vous avez effectué n’est pas valide. Cela peut être dû à l’une des raisons suivantes : | |
Erreur d’API | Un problème est survenu au niveau de Stripe (cas rare). | |
Erreur d’idempotence | Vous avez utilisé une clé d’idempotence pour effectuer une action inattendue (par exemple, relancer une requête en transmettant des paramètres différents). |
Erreurs de carte
Les erreurs de paiement, parfois appelées « erreurs de carte » pour des raisons historiques, regroupe un grand nombre de problèmes courants. Elles sont réparties en trois catégories :
Pour pouvoir distinguer ces catégories ou en savoir davantage sur la façon d’y répondre, reportez-vous aux pages relatives aux codes d’erreur, aux codes de refus de paiement et aux résultats du paiement.
(Pour rechercher un résultat de paiement à partir d’un objet Error, récupérez d’abord le PaymentIntent correspondant ainsi que le dernier paiement que ce dernier a créé. L’exemple ci-après illustre cette étape.)
Utilisateurs de la version du 01/08/2022 de l’API ou d’une version antérieure :
(Pour rechercher un résultat de paiement à partir d’un objet Error, récupérez d’abord le PaymentIntent correspondant ainsi que le dernier paiement que ce dernier a créé. L’exemple ci-après illustre cette étape.)
Grâce aux cartes de test, vous pouvez déclencher certains types d’erreur de paiement courants. Consultez ces listes pour connaitre les démarches à suivre :
- Simulation de paiements bloqués en raison d’un risque de fraude
- Simulation de refus de paiements et d’autres erreurs de carte
Le code de test ci-dessous montre quelques possibilités.
Bloqué pour suspicion de fraude
Type |
|
Codes |
|
Codes |
|
Problème | Radar, le système de prévention des fraudes de Stripe, a bloqué le paiement |
Solutions | Cette erreur peut se produire alors que votre intégration fonctionne correctement. Capturez-la et invitez le client à utiliser un autre moyen de paiement. Pour bloquer moins de paiements légitimes, suivez la procédure ci-après :
Les clients de Radar for Fraud Teams disposent des options supplémentaires suivantes :
Vous pouvez tester les paramètres de votre intégration à l’aide de cartes de test qui permettent de simuler des fraudes. Si vous avez défini des règles Radar personnalisées, suivez les conseils en matière de test décrits dans la documentation de Radar. |
Refusé par l’émetteur
Type |
|
Codes |
|
Problème | L’émetteur de la carte a refusé le paiement. |
Solutions | Cette erreur peut se produire alors que votre intégration fonctionne correctement. Elle résulte d’une action effectuée par l’émetteur, qui peut être légitime. Utilisez le code de refus de paiement pour déterminer la marche à suivre. Consultez la documentation consacrée aux codes de refus de paiement pour découvrir les réponses adaptées à chaque code. Vous pouvez également effectuer les actions ci-après :
Analysez la façon dont votre intégration gère les refus de paiement à l’aide de cartes de test qui permettent de simuler des paiements aboutis et refusés. |
Autres erreurs de paiement
Type |
|
Problème | Une autre erreur de paiement s’est produite. |
Solutions | Cette erreur peut se produire alors que votre intégration fonctionne correctement. Utilisez le code d’erreur pour déterminer la marche à suivre. Consultez la documentation consacrée à ce sujet pour découvrir les réponses adaptées à chaque code. |
Erreurs de requêtes invalides
Les erreurs de requêtes invalides couvrent de nombreuses situations. La plus courante survient quand la requête à l’API contient des paramètres non valides ou si l’état actuel de votre intégration ne permet pas son exécution. Utilisez le code d’erreur (stripeErr.
) et consultez la documentation consacrée aux codes d’erreur afin de trouver une solution. Certains codes d’erreur nécessitent une réponse spéciale :
rate_
etlimit lock_
reflètent les erreurs de limite l’envoitimeout secret_
désigne une erreur d’authentificationkey_ required - D’autres codes d’erreur reflètent un des paramètres ou un état non valides
Erreurs de limite d’envoi
Type |
|
Codes | stripeErr. |
Problème | Vous avez effectué trop d’appels à l’API dans le délai imparti. |
Solutions |
|
Erreurs d’authentification
Type |
|
Codes | stripeErr. |
Problème | Stripe ne parvient pas à vous authentifier avec les informations que vous avez fournies. |
Solutions |
|
Paramètres ou état non valides
Type |
|
Codes | stripeErr. |
Problème | Vous avez effectué un appel à l’API contenant des paramètres incorrects, dont l’état est incompatible ou d’une manière non valide. |
Solutions | Dans la plupart des cas, le problème vient de la requête elle-même : soit ses paramètres ne sont pas valides, soit l’état actuel de votre intégration ne permet pas son exécution.
|
Erreurs d’API
Type |
|
Problème | Un problème est survenu au niveau de Stripe (cas rare). |
Solutions | Traitez le résultat de l’appel à l’API comme étant indéterminé. Autrement dit, ne partez pas du principe qu’il a abouti ou échoué. Appuyez-vous sur les webhooks pour obtenir des informations sur le résultat. Lorsque cela est possible, Stripe déclenche des webhooks pour tous les nouveaux objets créés pendant la résolution du problème. Pour configurer votre intégration de sorte à ce qu’elle soit capable de gérer des situations inhabituelles, reportez-vous à cette section plus avancée consacrée aux erreurs de serveur. |
Erreurs d’idempotence
Type |
|
Problème | Vous avez utilisé une clé d’idempotence pour effectuer une action inattendue (par exemple, relancer une requête en transmettant des paramètres différents). |
Solutions |
|