Utilisation des webhooks avec les abonnements

Vous recevez des notifications de Stripe dans votre application par le biais d’événements de webhook. Utilisez des événements de webhook pour gérer les abonnements, car la plupart des activités se déroulent de manière asynchrone. Traitez ces événements au niveau d’un endpoint de webhook ou d’autres destinations telles qu’Amazon EventBridge en créant une destination d’événement.

Pour utiliser les webhooks avec vos abonnements :

1. Créez un endpoint de webhook dans votre application.
2. Inscrire votre endpoint de webhook dans Workbench
3. Ajoutez la logique voulue pour gérer les événements Stripe. Pour les abonnements, il s’agit principalement de traiter les échecs de paiement et les changements d’état de l’abonnement (comme le basculement d’une période d’essai à l’état actif). Vous pouvez utiliser le guide de démarrage rapide du webhook pour créer un endpoint de webhook minimal.
4. Testez votre endpoint de webhook pour confirmer qu’il fonctionne comme prévu.

Si votre application s’exécute sur AWS, vous pouvez configurer Stripe de façon à envoyer les événements directement à AWS EventBridge dans votre compte AWS.

Gérer les échecs de paiement

Les événements constituent un moyen sûr pour Stripe de vous informer des échecs de paiement de vos factures d’abonnement. Certains échecs de paiement sont temporaires : par exemple, l’émetteur de la carte peut refuser le débit initial, mais autoriser une nouvelle tentative automatique par la suite. D’autres échecs de paiement sont en revanche définitifs, comme ceux liés à l’absence de moyen de paiement utilisable pour le client, et nécessitent une action.

Veuillez vous reporter au guide de présentation des abonnements pour en savoir plus sur la façon de gérer les échecs de paiement qui nécessitent un moyen de paiement.

Gérer les paiements nécessitant une action supplémentaire

Certains moyens de paiement peuvent nécessiter des étapes supplémentaires, comme une authentification du client, pour que l’opération puisse aboutir. Si vous recevez de tels événements, votre application doit notifier le client pour qu’il effectue l’action requise. Pour plus d’informations sur la façon de gérer les événements nécessitant une action supplémentaire, consultez le guide de présentation des abonnements.

Suivre les abonnements actifs

Les abonnements nécessitent une coordination entre votre site et Stripe. La réussite ou l’échec des paiements récurrents d’un client détermine s’il peut continuer à accéder à votre produit ou service.

Dans une intégration type, vous stockez les identifiants de vos clients et une valeur d’horodatage associée qui représente la date d’expiration de l’accès du client sur votre site lorsqu’un client s’abonne. Lorsque le client se connecte, vous pouvez vérifier si l’horodatage est toujours dans le futur. Si c’est le cas lors de la connexion du client, le compte est actif et le client doit toujours avoir accès au service.

Lors du renouvellement de l’abonnement, Stripe facture le client et tente de percevoir le paiement en débitant automatiquement le moyen de paiement enregistré ou en envoyant la facture par e-mail aux clients. Stripe informe votre site de l’état de la facture par l’envoi d’un événement de webhook :

1. Votre site reçoit un événement invoice.paid.

   • Lors du débit automatique d’un moyen de paiement, votre site reçoit d’abord un événement invoice.upcoming sur l’endpoint de votre webhook configuré quelques jours avant le renouvellement. Vous pouvez écouter cet événement pour ajouter des postes supplémentaires à la facture à venir. En présence du paramètre collection_method=send_invoice, Stripe n’envoie pas d’événement invoice.upcoming.

2. Votre application trouve le client pour lequel le paiement a été effectué.

3. Votre application met à jour la date d’expiration de l’accès du client dans votre base de données sur la date à venir appropriée (plus un ou deux jour(s) de marge).

Capturer les changements d’état des abonnements

Assurez-vous que votre intégration surveille et gère correctement les changements d’état des abonnements décrits dans le tableau suivant.

Certaines modifications d’état requièrent une attention particulière :

• Quelques jours avant la fin de la période d’essai et le passage de l’abonnement de l’état trialing à active, vous recevez un événement customer.subscription.trial_will_end. À la réception de cet événement, vérifiez qu’un moyen de paiement est défini pour le client afin de pouvoir le facturer. Si vous le souhaitez, vous pouvez prévenir le client qu’il va être débité.

• Lorsqu’un abonnement bascule à l’état past_due, prévenez votre client directement et demandez-lui de mettre ses données de paiement à jour. Stripe propose plusieurs fonctionnalités pour automatiser ce processus. Reportez-vous à la page consacrée au recouvrement de revenus.

• Lorsqu’un abonnement passe à l’état canceled ou unpaid, révoquez l’accès à votre produit.

Webhook endpoints and invoices

Register a webhook endpoint to keep track of invoice statuses. Your subscription integration depends on correctly finalizing invoices and properly handling invoice finalization failures.

Lorsque vous activez l’encaissement automatique, Stripe finalise automatiquement la facture et lance son encaissement automatique.

• If Stripe fails to receive a successful response to invoice.created, we delay finalizing all invoices with automatic collection for up to 72 hours, excluding those where you have set a custom scheduled finalization time.
• Répondre correctement à invoice.created implique la gestion de tous les endpoints de webhook configurés pour votre compte, ainsi que les endpoints de webhook de toutes les plateformes auxquelles vous vous êtes connecté.
• Mettre à jour un abonnement pour tenter des paiements en mode synchrone (sur la facture initiale et certaines mises à jour) n’entraîne pas ce délai.
• Invoice finalization failure prevents payment collection for the invoice. Make sure you listen for the invoice.finalization_failed event in your webhook endpoint.

Événements webhook liés à la finalisation des factures

See a complete list of invoice event types.

Finalisation de facture réussie

Stripe attend une heure après réception d’une réponse de réussite pour l’événement invoice.created avant de tenter le paiement. Si nous ne recevons aucune réponse de réussite dans les 72 heures, nous tentons de finaliser la facture et de l’envoyer.

Si vous souhaitez traiter les factures ponctuelles différemment des factures d’abonnement, cochez la propriété subscription dans le corps du webhook. Ceci permet d’indiquer si la facture a été créée pour un abonnement.

In live mode, if your webhook endpoint doesn’t respond properly, Stripe continues retrying the webhook notification for up to 3 days with an exponential back off. In a sandbox, we retry three times over a few hours. During that time, we won’t attempt to charge the customer unless we receive a successful response. We’ll also send you an email to notify you that the webhook is failing.

Ce comportement s’applique à tous les endpoints de webhook définis sur votre compte, y compris les cas où une application Stripe Connect ou un service tiers rencontre des problèmes pour gérer les webhooks entrants.

Échec de la finalisation de facture

Lorsque Stripe n’est pas en mesure de finaliser une facture, il envoie un événement invoice.finalization_failed à votre endpoint de webhook. Un abonnement reste actif lorsqu’une facture ne peut pas être finalisée, ce qui signifie que l’utilisateur reste en capacité d’accéder à votre produit tandis que vous ne pouvez pas percevoir ses paiements. Veillez à prendre les mesures utiles pour vos factures non finalisées. Vous ne pouvez pas percevoir de paiements pour une facture qui n’a pas été finalisée.

Pour déterminer la raison de l’échec de la finalisation de la facture, inspectez le champ last_finalization_error de l’objet Invoice, qui vous fournira davantage d’informations sur l’échec et vous renseignera sur la manière d’y remédier.

If you’re using Stripe Tax, check if the automatic_tax.status field is requires_location_inputs, indicating that the address details are invalid or insufficient. If Stripe Tax can’t find a recognized customer location, we can’t finalize the invoice. Learn how to handle invoice finalization failures.

Tests

To test your webhook endpoint or event destination, choose one of these two options:

1. Perform actions in test mode that send legitimate events to your event destination. For example, to trigger the charge.succeeded event, you can use a test card that produces a successful charge.
2. Déclenchez des événements à l’aide de l’interface de ligne de commande Stripe ou via Stripe pour Visual Studio Code.