Accéder directement au contenu
Créez un compte
 ou
connecter-vous
Logo de la documentation Stripe
/
Créez un compte
Connectez-vous

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.

TechniqueObjectifNécessaire
Capturer les exceptionsRectifier les problèmes en cas d’interruption d’un appel à l’APISystématiquement
Surveiller les webhooksRéagir aux notifications de StripeParfois
Obtenir des informations enregistrées sur les échecsAnalyser les problèmes passés et prendre en charge d’autres techniquesParfois

Capturer les exceptions

Si un problème immédiat empêche la poursuite d’un appel à l’API, la bibliothèque Ruby de Stripe génère une exception. Nous vous conseillons vivement de capturer et de traiter ces exceptions.

Pour capturer une exception, utilisez le mot clé Ruby rescue. Capturez Stripe::StripeError ou ses sous-classes afin de traiter uniquement les exceptions spécifiques à Stripe. Chaque sous-classe représente un type d’exception distinct. Lorsque vous capturez une exception, vous pouvez utiliser sa classe pour choisir une réponse.

require 'stripe'

Stripe.api_key = 
'sk_test_09l3shTSTKHYCzzZZsiLl2vA'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    puts "A payment error occurred: #{e.error.message}"
  rescue Stripe::InvalidRequestError => e
    puts "An invalid request occurred."
  rescue Stripe::StripeError => e
    puts "Another problem occurred, maybe unrelated to Stripe."
  else
    puts "No error."
  end
end

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.

example_function(
  # The required parameter currency is missing,
  amount: 2000,
  confirm: true,
  payment_method: 
'pm_card_visa'
,
)
console
An invalid request occurred.

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 :

  1. Accédez à event.data.object pour récupérer l’objet concerné.
  2. Utilisez les informations stockées dans l’objet concerné pour obtenir des explications, y compris dans le cas d’un objet Error.
  3. Référez-vous au type de l’objet pour déterminer la marche à suivre.
require 'stripe'
require 'sinatra'
post '/webhook' do
  payload = request.body.read
  data = JSON.parse(payload, symbolize_names: true)

  # Get the event object
  event = Stripe::Event.construct_from(data)

  # Use the event type to find out what happened
  case event.type
  when 'payment_intent.payment_failed'

    # Get the object affected
    payment_intent = event.data.object

    # Use stored information to get an error object
    e = payment_intent.last_payment_error

    # Use its type to choose a response
    case e.type
    when 'card_error'
      puts "A payment error occurred: #{e.message}"
    when 'invalid_request'
      puts "An invalid request occurred."
    else
      puts "Another problem occurred, maybe unrelated to Stripe."
    end
  end

  content_type 'application/json'
  {
    status: 'success'
  }.to_json
end

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.

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 référer à sa classe pour déterminer la marche à suivre.

Par exemple :

  1. Récupérez un PaymentIntent spécifique.
  2. Vérifiez s’il y a eu une erreur de paiement en déterminant si l’objet last_payment_error est vide.
  3. Si c’est le cas, consignez l’erreur en incluant son type et l’objet concerné.
require 'stripe'
Stripe.api_key = 
'sk_test_09l3shTSTKHYCzzZZsiLl2vA'


payment_intent = Stripe::PaymentIntent.retrieve(
'{{PAYMENT_INTENT_ID}}'
)
e = payment_intent.last_payment_error
if !e.nil?
  puts "PaymentIntent #{payment_intent.id} experienced a #{e.type}."
end

Voici quelques objets courants qui stockent des informations sur les échecs.

ObjetAttributValeurs
Payment Intentslast_payment_errorUn objet Error
Setup Intentslast_setup_errorUn objet Error
Invoicelast_finalization_errorUn objet Error
Setup Attemptsetup_errorUn objet Error
Virementfailure_codeUn code d’échec de virement
Refundfailure_reasonUn 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 :

Types d’erreurs et réponses

Dans la bibliothèque Ruby de Stripe, les objets Error appartiennent à la classe stripe.error.StripeErroret ses sous-classes. Référez-vous à la documentation concernant chaque classe pour obtenir des conseils quant aux réponses à apporter.

Nom

Classe

Description
Erreur de paiement

Stripe::CardError

Une erreur est survenue lors d’un paiement. Voici les cas possibles :
Erreur de requête non valide

Stripe::InvalidRequestError

Vous avez effectué un appel à l’API contenant des paramètres incorrects, dont l’état est incompatible ou d’une manière non valide.

Erreur de connexion

Stripe::APIConnectionError

Un problème réseau est survenu entre votre serveur et Stripe.
Erreur d’API

Stripe::APIError

Un problème est survenu au niveau de Stripe (cas rare).
Erreur d’authentification

Stripe::AuthenticationError

Stripe ne parvient pas à vous authentifier avec les informations que vous avez fournies.
Erreur d’idempotence

Stripe::IdempotencyError

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).
Erreur d’autorisation

Stripe::PermissionError

La clé API utilisée pour cette requête ne dispose pas des autorisations nécessaires.
Erreur de limite d’envoi

Stripe::RateLimitError

Vous avez effectué trop d’appels à l’API dans le délai imparti.
Erreur de vérification de signature

Stripe::SignatureVerificationError

Vous utilisez la vérification de signature de webhook et n’avez pas pu vérifier l’authenticité d’un événement webhook.

Erreurs de paiement

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.)

require 'stripe'
Stripe.api_key = 
'sk_test_09l3shTSTKHYCzzZZsiLl2vA'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge)
    if charge.outcome.type == 'blocked'
      puts 'Payment blocked for suspected fraud.'
    elsif e.code == 'card_declined'
      puts 'Payment declined by the issuer.'
    elsif e.code == 'expired_card'
      puts 'Card expired.'
    else
      puts 'Other card error.'
    end
  end
end

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.)

require 'stripe'
Stripe.api_key = 
'sk_test_09l3shTSTKHYCzzZZsiLl2vA'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    if e.error.payment_intent.charges.data[0].outcome.type == 'blocked'
      puts 'Payment blocked for suspected fraud.'
    elsif e.code == 'card_declined'
      puts 'Payment declined by the issuer.'
    elsif e.code == 'expired_card'
      puts 'Card expired.'
    else
      puts 'Other card error.'
    end
  end
end

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 :

Le code de test ci-dessous montre quelques possibilités.

example_function(
  currency: 'usd',
  amount: 2000,
  confirm: true,
  payment_method: 
'pm_card_radarBlock'
,
)
console
Payment blocked for suspected fraud.

Paiement bloqué pour suspicion de fraude

Type

Stripe::CardError

Codes
charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge)
charge.outcome.type == 'blocked'
Codes

e.error.payment_intent.charges.data[0].outcome.type == 'blocked'

ProblèmeRadar, 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 :

  • Pour exempter un paiement spécifique, ajoutez-le à votre liste blanche. Radar for Fraud Teams
  • Pour modifier votre seuil de tolérance au risque, réajustez les paramètres de risque. Radar for Fraud Teams
  • Pour modifier les critères de blocage des paiements, définissez des règles personnalisées. Radar for Fraud Teams

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.

Paiement refusé par l’émetteur

Type

Stripe::CardError

Codes

e.error.code == "card_declined"

ProblèmeL’é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

Stripe::CardError

ProblèmeUne autre erreur de paiement s’est produite.
SolutionsCette 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

Type

Stripe::InvalidRequestError

ProblèmeVous avez effectué un appel à l’API contenant des paramètres incorrects, dont l’état est incompatible ou d’une manière non valide.
SolutionsDans 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 en savoir plus à propos de ce problème, consultez la documentation consacrée aux codes d’erreur.
  • Pour des raisons pratiques, vous pouvez suivre le lien pour en savoir plus sur le code d’erreur.
  • Si l’erreur implique un paramètre précis, utilisez pour savoir duquel il s’agit.

Erreurs de connexion

Type

Stripe::APIConnectionError

ProblèmeUn problème réseau est survenu entre votre serveur et Stripe.

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é.

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 :

  • Lorsque vous créez ou mettez à jour un objet, utilisez une clé d’idempotence. Ensuite, si une erreur de connexion se produit, vous pouvez répéter l’opération en toute sécurité, sans risquer de créer un deuxième objet ni d’effectuer deux fois la mise à jour. Réitérez la requête avec la même clé d’idempotence jusqu’à aboutir à une réussite ou un échec. Pour obtenir des conseils plus avancés sur cette stratégie, reportez-vous à la section consacrée à la gestion des erreurs de bas niveau.
  • Activez les relances automatiques. Ensuite, Stripe génère des clés d’idempotence et relance les requêtes en temps opportun.

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

Stripe::APIError

ProblèmeUn 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’authentification

Type

Stripe::AuthenticationError

ProblèmeStripe ne parvient pas à vous authentifier avec les informations que vous avez fournies.
Solutions

Erreurs d’idempotence

Type

Stripe::IdempotencyError

ProblèmeVous 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
  • 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

Stripe::PermissionError

ProblèmeLa 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 ?
  • Effectuez-vous une action via le Dashboard tout en étant connecté avec un rôle utilisateur pour lequel certains accès sont limités ?

Erreurs de limite d’envoi

Type

Stripe::RateLimitError

ProblèmeVous avez effectué trop d’appels à l’API dans le délai imparti.
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 d’envoi.
  • Si vous prévoyez une augmentation importante du trafic et que vous souhaitez demander une limite d’envoi plus souple, contactez notre service d’assistance en amont.

Erreurs de vérification de signature

Type

Stripe::SignatureVerificationError

ProblèmeVous utilisez la vérification de signature de webhook et n’avez pas pu vérifier l’authenticité d’un événement webhook.

Solutions

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 qu’elle n’est pas censée apparaître (par exemple, avec des webhooks qui proviennent de Stripe), alors consultez la documentation consacrée à la vérification des signatures de webhook pour en savoir plus. Veillez plus particulièrement à utiliser la clé secrète de l’endpoint adaptée (qui n’est pas votre clé API).

Cette page vous a-t-elle été utile ?
OuiNon
Besoin d'aide ? Contactez le service d'assistance.
Rejoignez notre programme d'accès anticipé.
Consultez notre journal des modifications des produits.
Des questions ? Contactez l'équipe commerciale.
Propulsé par Markdoc
Sur cette page
Capturer les exceptions
Surveiller les webhooks
Obtenir des informations enregistrées sur les échecs
Types d’erreurs et réponses
Erreurs de paiement
Payment blocked
Payment declined
Other payment errors
Invalid request errors
Connection errors
API errors
Authentication errors
Idempotency errors
Permission errors
Rate limit errors
Signature verification errors