Webhooks in Verbindung mit Abonnements verwenden

Sie erhalten Benachrichtigungen von Stripe in Ihrer App über Webhook-Ereignisse. Verwenden Sie Webhook-Ereignisse zum Verwalten von Abonnements, da die meisten Aktivitäten asynchron ablaufen. Verarbeiten Sie diese Ereignisse an einem Webhook-Endpoint oder anderen Zielen wie Amazon EventBridge, indem Sie ein Ereignisziel erstellen.

So verwenden Sie Webhooks in Verbindung mit Ihren Abonnements:

1. Erstellen Sie einen Webhook-Endpoint in Ihrer App.
2. Ihren Webhook-Endpoint in Workbench registrieren
3. Fügen Sie Logik zur Verarbeitung von Stripe-Ereignissen hinzu. Bei Abonnements zählen dazu fehlgeschlagene Zahlungen und Änderungen des Abonnementstatus (z. B. der Wechsel von einer Testversion zu einem aktiven Status). Sie können die Webhook-Quickstart-Anleitung verwenden, um einen minimalen Webhook-Endpoint zu erstellen.
4. Testen Sie Ihren Webhook-Endpoint, um zu bestätigen, dass er wie erwartet funktioniert.

Wenn Ihre Anwendung auf AWS ausgeführt wird, können Sie Stripe so konfigurieren, dass Ereignisse direkt an AWS EventBridge in Ihrem AWS-Konto gesendet werden.

Umgang mit fehlgeschlagenen Zahlungen

Ereignisse bieten eine zuverlässige Möglichkeit für Stripe, Sie über fehlgeschlagene Zahlungen bei Abonnementrechnungen zu benachrichtigen. Einige fehlgeschlagene Zahlungen sind nur temporär, z. B. kann ein/e Kartenaussteller/in die erste Zahlung ablehnen, aber eine automatische Wiederholung zulassen. Andere fehlgeschlagene Zahlungen sind endgültig und machen Maßnahmen erforderlich, z. B. das Fehlen einer nutzbaren Zahlungsmethode für den Kunden/die Kundin.

Umgang mit Zahlungen, für die zusätzliche Maßnahmen erforderlich sind

Bei einigen Zahlungsmethoden sind möglicherweise zusätzliche Schritte erforderlich, z. B. die Authentifizierung des Kunden/der Kundin. Wenn Sie diese Ereignisse erhalten, muss Ihre App den Kunden/die Kundin benachrichtigen, damit er/sie die erforderliche Aktion abschließt. Um zu erfahren, wie Sie mit Ereignissen, die zusätzliche Maßnahmen erfordern umgehen, lesen Sie den Leitfaden mit einer Übersicht über Abonnements.

Aktive Abonnements verfolgen

Für Abonnements ist eine Koordination zwischen Ihrer Website und Stripe erforderlich. Ob die wiederkehrenden Zahlungen eines Kunden/einer Kundin erfolgreich sind, bestimmt, ob diese weiterhin Zugang zu Ihrem Produkt oder Ihrer Dienstleistung haben.

Bei typischen Integrationen speichern Sie die Anmeldedaten der Kundinnen/Kunden und einen zugeordneten Zeitstempelwert, der das Ablaufdatum des Zugangs für diese Kundin/diesen Kunden auf Ihrer Website darstellt, wenn eine Kundin/ein Kunde ein Abonnement abschließt. Wenn sich ein Kundin/ein Kunde anmeldet, prüfen Sie, ob der Zeitstempel immer noch in der Zukunft liegt. Liegt der Zeitstempel in der Zukunft, wenn sich die Kundin/der Kunde anmeldet, ist das Konto weiterhin aktiv, und die Kundin/der Kunde sollte weiterhin Zugang zu der Dienstleistung haben.

Wenn das Abonnement verlängert wird, stellt Stripe dem Kunden/der Kundin eine Rechnung aus und versucht, die Zahlung einzuziehen, und zwar entweder durch automatische Belastung der hinterlegten Zahlungsmethod oder indem die Rechnung per E-Mail an den Kunden/die Kundin gesendet wird. Stripe informiert Ihre Website über den Status der Rechnung, indem ein Webhook-Ereignis gesendet wird:

1. Ihre Website empfängt das Ereignis invoice.paid.

   • Wenn Sie eine Zahlungsmethode automatisch belasten, erhält Ihre Website einige Tage vor der Verlängerung zunächst das Ereignis invoice.upcoming am konfigurierten Webhook-Endpoint. Sie können dieses Ereignis überwachen, um der zukünftigen Rechnung zusätzliche Rechnungsposten hinzuzufügen. Wenn collection_method=send_invoice, sendet Stripe kein Ereignis invoice.upcoming.

2. Ihre Anwendung findet den Kunden/die Kundin, für den/die die Zahlung getätigt wurde.

3. Ihre Anwendung aktualisiert das Ablaufdatum für den Zugriff des Kunden/der Kundin in Ihrer Datenbank auf das entsprechende Datum in der Zukunft (zuzüglich ein bis zwei Tagen Spielraum).

Statusänderungen von Abonnements erfassen

Stellen Sie sicher, dass Ihre Integration die Übergänge zwischen den in der folgenden Tabelle beschriebenen Abonnementstatus ordnungsgemäß überwacht und handhabt.

Einige Statusänderungen erfordern besondere Aufmerksamkeit:

• Einige Tage vor Ablauf eines Testzeitraums, wenn das Abonnement von trialing zu active wechselt, erhalten Sie das Ereignis customer.subscription.trial_will_end. Wenn Sie dieses Ereignis erhalten, überprüfen Sie, ob Sie eine Zahlungsmethode für die Kundin/den Kundin haben, damit Sie ihr/sein Konto belasten können. Informieren Sie die Kundin/den Kunden optional über die Belastung.

• Wenn der Status eines Abonnements zu past_due wechselt, benachrichtigen Sie die Kundinnen/Kunden direkt und bitten Sie sie, ihre Zahlungsdaten zu aktualisieren. Stripe bietet mehrere Funktionen zur Automatisierung dieses Vorgangs. Erfahren Sie mehr über die Umsatzsicherung.

• Wenn der Status eines Abonnements zu canceled oder unpaid wechselt, widerrufen Sie den Zugriff auf Ihr Produkt.

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.

Wenn Sie den automatischen Einzug aktivieren, führt Stripe die Finalisierung automatisch durch und beginnt mit dem automatischen Einzug der Rechnung.

• 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.
• Responding properly to invoice.created includes handling all webhook endpoints configured for your account, along with the webhook endpoints of any platforms that you’ve connected to. This doesn’t include any webhook endpoints configured in an organization. While you can listen to invoice.created at the organization, a successful response doesn’t affect invoice finalization when using automatic collection.
• Die Aktualisierung eines Abonnements mit synchronen Zahlungsversuchen (bei der ersten Rechnung und bei einigen Arten von Aktualisierungen) führt nicht zu dieser Verzögerung.
• Invoice finalization failure prevents payment collection for the invoice. Make sure you listen for the invoice.finalization_failed event in your webhook endpoint.

Webhook-Ereignisse im Zusammenhang mit der Rechnungsfinalisierung

See a complete list of invoice event types.

Erfolgreiche Rechnungsfinalisierung

Stripe wartet eine Stunde nach Erhalt einer erfolgreichen Antwort auf das Ereignis invoice.created, bevor ein Zahlungsversuch gestartet wird. Wenn innerhalb von 72 Stunden keine erfolgreiche Antwort eingeht, versucht Stripe, die Rechnung zu finalisieren und zu senden.

Falls Sie einmalige Rechnungen anders behandeln möchten als Abonnementrechnungen, prüfen Sie die Eigenschaft subscription im Webhook-Text. Hier wird angezeigt, ob die Rechnung für ein Abonnement erstellt wurde.

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.

Dieses Verhalten gilt für alle auf Ihrem Konto angegebenen Webhook-Endpoints, einschließlich für Fälle, in denen eine Connect-Anwendung oder ein anderer Drittanbieter Schwierigkeiten beim Empfang eingehender Webhooks hat.

Fehler bei der Rechnungsfinalisierung

Wenn Stripe eine Rechnung nicht finalisieren kann, wird das Ereignis invoice.finalization_failed an Ihren Webhook-Endpoint gesendet. Abonnements bleiben aktiv, wenn Rechnungen nicht finalisiert werden können. Das bedeutet, dass Nutzer/innen weiterhin auf Ihr Produkt zugreifen können, während Sie nicht in der Lage sind, Zahlungen einzuziehen. Ergreifen Sie bei Rechnungen, die nicht finalisiert werden können, unbedingt entsprechende Maßnahmen. Für Rechnungen, die nicht finalisiert sind, können Sie keine Zahlungen einziehen.

Um festzustellen, warum die Rechnungsfinalisierung fehlgeschlagen ist, sehen Sie sich das Feld last_finalization_error des Rechnungsobjekts an, das weitere Informationen über den Fehler und die weitere Vorgehensweise enthält.

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 a sandbox 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. Ereignisse mit der Stripe-CLI oder mit Stripe für Visual Studio Code auslösen.