Accéder directement au contenu
Créez un compte
 ou
connectez-vous
Le logo de la documentation Stripe
/
Créer un compte
Connectez-vous
Aperçu
Contrôle de version
Mettre à niveau votre version de l'API
Outils de développement
Développer avec des GMLStripe pour Visual Studio CodeAlertes sur la santé de StripeTéléversements de fichier
Sécurité et confidentialité
Étendez Stripe
Partenaires
Certification des partenaires

Gestion des erreurs

Capturer et répondre aux refus de paiement, aux données non valides, aux problèmes de réseau, etc.

Copier la page

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.

TechniqueObjectifSi nécessaire
Capturer les exceptionsRectifier les problèmes en cas d’interruption d’un appel à l’APIToujours
Suivre les webhooksRéagir aux notifications de StripeParfois
Obtenir des informations enregistrées sur les échecsAnalyser les problèmes antérieurs et soutenir d’autres techniquesParfois

Capturer les exceptions

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

Pour capturer une exception, utilisez la syntaxe PHP try/catch. Stripe propose plusieurs classes d’exceptions que vous pouvez capturer. Chacune d’entre elles représente un type d’erreur distinct. Lorsque vous capturez une exception, vous pouvez utiliser sa classe pour choisir une réponse.

<?php
require 'vendor/autoload.php';
\Stripe\Stripe::setApiKey(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

function example_function($args) {
  try {
    $stripe->paymentIntents->create($args);
    error_log("No error.");
  } catch(\Stripe\Exception\CardException $e) {
    error_log("A payment error occurred: {$e->getError()->message}");
  } catch (\Stripe\Exception\InvalidRequestException $e) {
    error_log("An invalid request occurred.");
  } catch (Exception $e) {
    error_log("Another problem occurred, maybe unrelated to Stripe.");
  }
}

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.

Suivre 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 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 :

  1. Accédez à event->data->object pour récupérer l’objet affecté.
  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.
<?php
require 'vendor/autoload.php';
\Stripe\Stripe::setApiKey(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

$payload = @file_get_contents('php://input');
$event = null;

// Get the event object
try {
  $event = \Stripe\Event::constructFrom(
    json_decode($payload, true)
  );
} catch(\UnexpectedValueException $e) {
  echo '⚠️  Webhook error while parsing basic request.';
  http_response_code(400);
  exit();
}

// Use the event type to find out what happened
if ($event->type == 'payment_intent.payment_failed') {

  // Get the object affected
  $paymentIntent = $event->data->object;

  // Use stored information to get an error object
  $e = $paymentIntent->last_payment_error;

  // Use its type to choose a response
  switch ($e->type) {
    case \Stripe\Exception\CardException:
      error_log("A payment error occurred: {$e->getError()->message}");
      break;
    case \Stripe\Exception\InvalidRequestException:
      error_log("An invalid request occurred.");
      if (isset($e->getError()->param)) {
        error_log("The parameter {$e->getError()->param} is invalid or missing.");
      }
      break;
    default:
      error_log("Another problem occurred, maybe unrelated to Stripe.");
  }
}

http_response_code(200);

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 :

  1. Récupérez un Payment Intent spécifique.
  2. Vérifiez s’il y a eu une erreur de paiement en déterminant si last_payment_error est vide.
  3. Si c’est le cas, consignez l’erreur en incluant son type et l’objet concerné.
<?php
  require 'vendor/autoload.php';

  \Stripe\Stripe::setApiKey(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

  payment_intent = $stripe->paymentIntents->retrieve(% identifier type="paymentIntent" /%});

  e = payment_intent->last_payment_error
  if isset(e) {
    error_log("PaymentIntent {$payment_intent->id} experienced a {$e->getError()->type} error.")
  }

Voici des objets courants qui enregistrent des informations sur les échecs.

ObjetAttributValeurs
Payment Intentlast_payment_errorUn objet Error
Setup Intentlast_setup_errorUn objet Error
Facturelast_finalization_errorUn objet Error
Tentative de configurationsetup_errorUn objet Error
Virementfailure_codeUn code d’échec de virement
Remboursementfailure_reasonUn code d’échec de remboursement

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 le faire à l’aide de cartes de test ou de numéros de comptes bancaires de test. Par exemple :

Types d’erreurs et réponses

Dans la bibliothèque PHP de Stripe, chaque type d’erreur appartient à sa propre classe Reportez-vous à la documentation concernant chaque classe pour obtenir des conseils quant aux réponses à apporter.

Nom

Classe

Description
Erreur de paiement

Stripe\Exception\CardException

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

Stripe\Exception\InvalidRequestException

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\Exception\ApiConnectionException

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

Stripe\Exception\ApiErrorException

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

Stripe\Exception\AuthenticationException

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

Stripe\Exception\IdempotencyException

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\Exception\PermissionException

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

Stripe\Exception\RateLimitException

Vous avez effectué trop d’appels à l’API en un temps réduit.
Erreur de vérification de signature

Stripe\Exception\SignatureVerificationException

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, consultez les sections 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.)

<?php
  require 'vendor/autoload.php';
  \Stripe\Stripe::setApiKey(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

  function example_function($args) {
    try {
      $stripe->paymentIntents->create($args);
    } catch(\Stripe\Exception\CardException $e) {
      $charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge);
      if ($charge->outcome->type == 'blocked') {
        error_log('Blocked for suspected fraud.');
      } elseif ($e->getError()->code == 'expired_card') {
        error_log('Card expired.');
      } elseif ($e->getError()->code == 'card_declined') {
        error_log('Declined by the issuer.');
      } else {
        error_log('Other card error.');
      }
    }
  }

Utilisateurs de la version de l’API 2022-08-01 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.)

<?php
  require 'vendor/autoload.php';
  \Stripe\Stripe::setApiKey(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'
);

  function example_function($args) {
    try {
      $stripe->paymentIntents->create($args);
    } catch(\Stripe\Exception\CardException $e) {
      if ($e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked') {
        error_log('Blocked for suspected fraud.');
      } elseif ($e->getError()->code == 'expired_card') {
        error_log('Card expired.');
      } elseif ($e->getError()->code == 'card_declined') {
        error_log('Declined by the issuer.');
      } else {
        error_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 :

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\Exception\CardException

Codes
$charge = $stripe->charge->retrieve($e->getError()->payment_intent->latest_charge);
charge->outcome->type == 'blocked'
Codes

$e->getError()->payment_intent->charges->data[0]->outcome->type == 'blocked'

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

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

Paiement refusé par l’émetteur

Type

Stripe\Exception\CardException

Codes

$e->getError()->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 normalement. Elle reflète une action effectuée par l’émetteur, qui peut être légitime. Utilisez le code de refus pour déterminer la marche à suivre. Consultez la documentation sur les codes de refus de paiement pour connaître 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 réussis et refusés.

Autres erreurs de paiement

Type

Stripe\Exception\CardException

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 sur les codes d’erreur pour connaître les réponses adaptées à chaque code.

Erreurs de requêtes invalides

Type

Stripe\Exception\InvalidRequestException

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 sur ce problème, consultez la documentation sur les codes d’erreur.
  • Pour des raisons pratiques, vous pouvez suivre le lien e->getError()->doc_url pour en savoir plus sur le code d’erreur.
  • Si l’erreur implique un paramètre particulier, utilisez e->getError()->param pour déterminer lequel.

Erreurs de connexion

Type

Stripe\Exception\ApiConnectionException

ProblèmeUne 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 résoudre les problèmes de connexion, vous pouvez effectuer les actions suivantes :

  • Lorsque vous créez un objet ou le mettez à jour, utilisez une clé d’idempotence. Ensuite, si une erreur de connexion se produit, vous pourrez 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 une réponse claire de succès ou d’échec. Pour obtenir des conseils plus avancés sur cette stratégie, consultez la section 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

Stripe\Exception\APIException

ProblèmeUn 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.

Pour définir votre intégration de sorte qu’elle puisse gérer des situations inhabituelles, consultez cette section plus avancée sur les erreurs de serveur.

Erreurs d’authentification

Type

Stripe\Exception\AuthenticationException

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

Erreurs d’idempotence

Type

Stripe\Exception\IdempotencyException

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\Exception\PermissionException

ProblèmeLa clé API utilisée pour cette requête ne dispose pas des autorisations nécessaires.
Solutions
  • Assurez-vous de ne pas utiliser de clé API restreinte pour un service auquel elle n’a pas accès.
  • N’effectuez pas d’actions dans le tableau de bord lorsque vous êtes connecté dans un rôle d’utilisateur et que vous n’avez pas les autorisations nécessaires.

Erreurs de limite de débit

Type

Stripe\Exception\RateLimitException

ProblèmeVous 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 de débit de façon automatique, refaites 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 taux.
  • 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.

Erreurs de vérification de signature

Type

Stripe\Exception\SignatureVerificationException

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 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 obtenir plus de conseils. En particulier, assurez-vous d’utiliser la bonne clé secrète du point de terminaison. Cette clé est différente de 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 questions? Contactez l'équipe commerciale.
GML? Lire llms.txt.
Optimisé par Markdoc