Capturer et répondre aux refus de paiement, aux données non valides, aux problèmes de réseau, etc.
Stripe présente plusieurs types d’erreurs. Elles peuvent refléter des événements extérieurs, tels que des paiements refusés et des interruptions de réseau, ou des problèmes de code, comme des appels à l’API non-valides.
Pour gérer les erreurs, utilisez toutes ou certaines des techniques présentées dans le tableau ci-dessous. Quelle que soit la technique utilisée, vous pouvez faire un suivi avec nos réponses recommandées pour chaque type d’erreur.
Analyser les problèmes antérieurs et soutenir d’autres techniques
Parfois
Capturer les exceptions
Si un problème immédiat empêche la poursuite d’un appel à l’API, la bibliothèque Node.js de Stripe peut générer une exception. Nous vous conseillons vivement de capturer et de traiter ces exceptions. Pour activer la génération d’exceptions et pouvoir les capturer par la suite, procédez de la manière suivante :
Si vous effectuez l’appel à l’API dans une fonction, précédez la définition de la fonction avec le mot-clé async.
Précédez l’appel à l’API avec le mot-clé await.
Enveloppez l’appel à l’API dans un bloc try/catch.
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.
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 application frontale confirme un paiement, mais se met hors ligne avant de détecter l’échec du paiement. (L’application dorsale continue de recevoir une notification de webhook, même si ce n’est pas celle qui a effectué l’appel à l’API.)
Vous n’avez pas besoin de gérer tous les types d’événements webhook. En fait, certaines intégrations n’en gèrent 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 :
);const express =require('express');const app =express();
app.post('/webhook', express.json({type:'application/json'}),(request, response)=>{// Get an event objectconst event = request.body;// Use its type to find out what happenedif(event.type=='payment_intent.payment_failed'){// Get the object affectedconst paymentIntent = event.data.object;// Use stored information to get an error objectconst error = paymentIntent.error;// Use its type to choose a responseswitch(error.type){case'StripeCardError':
console.log(`A payment error occurred: ${error.message}`);break;case'StripeInvalidRequestError':
console.log('An invalid request occurred.');if(error.param){
console.log(`The parameter ${error.param} is invalid or missing.`);}break;default:
console.log('Another problem occurred, maybe unrelated to Stripe.');break;}}
response.send();});
app.listen(4242,()=> console.log('Running on port 4242'));
Pour tester la façon dont votre intégration répond aux événements webhook, vous pouvez déclencher des événements webhook localement. Lorsque les étapes de configuration sont terminées sur ce lien, déclenchez un échec de paiement pour voir le message d’erreur généré.
Command Line
stripe trigger payment_intent.payment_failed
Output
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 reporter à sa classe pour déterminer la marche à suivre.
Par exemple :
Récupérez un Payment Intent spécifique.
Vérifiez s’il y a eu une erreur de paiement en déterminant si last_payment_error est vide.
Si c’est le cas, consignez l’erreur en incluant son type et l’objet concerné.
Pour tester un code qui utilise des informations enregistrées sur les échecs, vous devez fréquemment simuler des transactions qui ont échoué. Vous pouvez souvent le faire à l’aide de cartes de test ou de numéros de comptes bancaires de test. Par exemple :
Simuler un paiement refusé, pour avoir créé des frais, des PaymentIntents, des SetupIntents, etc. qui ont échoué.
Dans la bibliothèque Node.js de Stripe, chaque objet Error possède un attribut type. Reportez-vous à la documentation concernant chaque classe pour obtenir des conseils quant aux réponses à apporter.
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).
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 :
);asyncfunctionexampleFunction(args){try{const paymentIntent =await stripe.paymentIntents.create(args);}catch(e){
console.log(e)if(e.type==='StripeCardError'){if(e.payment_intent.charges.data[0].outcome.type==='blocked'){
console.log('Payment blocked for suspected fraud.')}elseif(e.code==='card_declined'){
console.log('Payment declined by the issuer.')}elseif(e.code==='expired_card'){
console.log('Card expired.')}else{
console.log('Other card error.')}}}}
Grâce aux cartes de test, vous pouvez déclencher certains types d’erreur de paiement courants. Consultez ces listes pour connaître les démarches à suivre :
Radar, le système de prévention des fraudes implémenté par 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 ce qui suit :
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 connaître les réponses adaptées à chaque code.
Vous pouvez également effectuer les actions ci-après :
Pour obtenir des éléments de formulaire préconfigurés qui puissent mettre en œuvre ces recommandations, utilisez Payment Links, Checkout ou Stripe Elements.
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 aux codes d’erreur pour découvrir les réponses adaptées à chaque code.
Erreurs de requêtes invalides
Type
StripeInvalidRequestError
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.
Pour des raisons pratiques, vous pouvez suivre le lien e.doc_url pour en savoir plus sur le code d’erreur.
Si l’erreur implique un paramètre particulier, utilisez e.param pour déterminer lequel.
Erreurs de connexion
Type
StripeAPIConnectionError
Problème
Une erreur réseau entre votre serveur et Stripe s’est produite.
Solutions
Traitez le résultat de l’appel à l’API comme indéterminé. Autrement dit, ne partez pas du principe qu’il a abouti ou échoué.
Pour savoir si cela a abouti, vous pouvez effectuer les actions suivantes :
Récupérez l’objet souhaité sur Stripe et consultez son état.
Écoutez des notifications de webhook afin de savoir si l’opération a abouti ou échoué.
Pour faciliter la correction des erreurs liées à la connexion, vous pouvez effectuer les actions suivantes :
Lors de la création ou de la mise à jour d’un objet, utilisez une clé d’idempotence. Ensuite, si une erreur de connexion se produit, vous pouvez répéter la demande en toute sécurité sans risquer de créer un deuxième objet ou d’effectuer la mise à jour deux fois. Répétez la demande avec la même clé d’idempotence jusqu’à ce que vous receviez un succès ou un échec clair. Pour des conseils avancés sur cette stratégie, voir Gestion des erreurs de bas niveau.
Activez les relances automatiques. Ensuite, Stripe génère des clés d’idempotence et réitère les requêtes lorsqu’il est opportun de le faire.
Cette erreur peut en cacher d’autres. Il peut arriver que d’autres erreurs apparaissent après en avoir résolu une.
Erreurs d’API
Type
StripeAPIError
Problème
Un problème est survenu au niveau de Stripe (cas rare).
Solutions
Traitez le résultat de l’appel à l’API comme 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.
Vous avez utilisé une clé d’idempotence pour effectuer une action inattendue (par exemple, renvoyer une requête mais en transmettant des paramètres différents).
Solutions
Une fois que vous avez utilisé une clé d’idempotence, ne la réutilisez que pour effectuer des appels à l’API identiques.
Utilisez des clés d’idempotence dont la longueur ne dépasse pas 255 caractères.
Erreurs d’autorisation
Type
StripePermissionError
Problème
La clé API utilisée pour cette requête ne dispose pas des autorisations nécessaires.
Solutions
Utilisez-vous une clé API limitée pour un service auquel elle n’a pas accès?
Are you performing an action in the Dashboard while logged in as a user role that lacks permission?
Erreurs de limite de débit
Type
StripeRateLimitError
Problème
Vous avez effectué trop d’appels à l’API dans un temps réduit.
Solutions
Si un seul appel à l’API déclenche cette erreur, réessayez ultérieurement.
Pour gérer la limitation d’envoi de façon automatique, retentez l’appel à l’API après quelques minutes et augmentez exponentiellement le délai si l’erreur persiste. Pour obtenir plus de conseils, consultez la documentation sur les limites de débit.
Si vous prévoyez une augmentation importante du trafic et que vous souhaitez demander une limite de débit plus souple, contactez notre service d’assistance en amont.
Cette erreur peut se produire alors que votre intégration fonctionne correctement. Si vous utilisez la vérification de signature de webhook et qu’un tiers tente de vous envoyer un faux webhook ou un webhook malveillant, alors la vérification échoue et une erreur survient. Capturez-la et renvoyez un code d’état 400 Bad Request.
Si vous recevez cette erreur alors que vous ne devriez pas, par exemple, avec des webhooks qui proviennent de Stripe, consultez la documentation sur la vérification des signatures de webhooks pour plus de conseils. En particulier, assurez-vous d’utiliser la bonne clé secrète pour le point de terminaison. Cette clé est différente de votre clé API.
Welcome to the Stripe Shell!
Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your
Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe
resources in test mode.
- View supported Stripe commands:
- Find webhook events:
- Listen for webhook events:
- Call Stripe APIs: stripe [api resource] [operation] (e.g., )
Le Shell Stripe est plus optimisé sur la version bureau.