Ereignisziele mit Abonnements nutzen

Stripe löst jedes Mal Ereignisse aus, wenn ein Abonnement erstellt oder geändert wird. Einige Ereignisse werden sofort gesendet, wenn ein Abonnement erstellt wird, während andere in regelmäßigen Abrechnungsintervallen auftreten.

Stellen Sie sicher, dass Ihre Integration die Ereignisse ordnungsgemäß handhabt. Sie können beispielsweise einem/einer Kund/in eine E-Mail senden, wenn eine Zahlung fehlschlägt oder den Zugriff eines Kunden/einer Kundin zurückziehen, wenn ein Abonnement storniert wird.

In der folgenden Tabelle werden die häufigsten Ereignisse im Zusammenhang mit Abonnements beschrieben und ggf. Maßnahmen zum Umgang mit den Ereignissen vorgeschlagen.

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/die Kund/in.

Weitere Informationen zum Umgang mit fehlgeschlagenen Zahlungen, für die eine Zahlungsmethode erforderlich ist finden Sie im Leitfaden mit einer Übersicht über Abonnements.

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.

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

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

Wenn das Abonnement verlängert wird, stellt Stripe eine Rechnung aus und versucht, die Zahlung einzuziehen, und zwar entweder durch automatische Belastung der hinterlegten Zahlungsmethode oder indem die Rechnung an die Kunden-E-Mail-Adresse gesendet wird. Stripe benachrichtigt Ihre Website per Ereignisziele über den Benachrichtigungsstatus:

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

   • Wenn Sie eine Zahlungsmethode automatisch belasten, empfängt Ihre Website einige Tage vor der Verlängerung zunächst das Ereignis invoice.upcoming an Ihre konfigurierten Ereignisziele. 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/der Kund/in in Ihrer Datenbank auf das entsprechende Datum in der Zukunft (zuzüglich ein bis zwei Tagen Spielraum).

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 auf active wechselt, erhalten Sie das Ereignis customer.subscription.trial_will_end. Wenn dies eintritt, ü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.

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.
• Die ordnungsgemäße Antwort auf invoice.created umfasst die Verarbeitung aller für Ihr Konto konfigurierten Webhook-Endpoints sowie der Webhook-Endpoints aller Plattformen, mit denen Sie verbunden sind.
• 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.

Wenn Ihr Webhook-Endpoint im Live-Modus nicht ordnungsgemäß reagiert, wiederholt Stripe die Webhook-Benachrichtigung bis zu drei Tage lang mit exponentiellem Zurücksetzen. Im Test-Modus versuchen wir es dreimal über mehrere Stunden hinweg. Während dieser Zeit versuchen wir nicht, das Kundenkonto zu belasten, solange wir keine Antwort bei Erfolg erhalten. Wir senden Ihnen außerdem eine E-Mail, um Sie über den fehlerhaften Webhook zu benachrichtigen.

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.

To test event destinations, 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. Ereignisse mit der Stripe-CLI oder mit Stripe für Visual Studio Code auslösen.