Weiter zum Inhalt
Konto erstellen
 oder
anmelden
Das Logo der Stripe-Dokumentation
/
Konto erstellen
Anmelden

Ereignisziele mit Abonnements nutzen

So verwenden Sie Ereignisziele, um Benachrichtigungen über Abonnementaktivitäten zu erhalten.

Stripe sendet mithilfe von Ereigniszielen Benachrichtigungen an Ihre Anwendung. Ereignisziele helfen bei der Verwaltung von Abonnements, wenn die meisten Vorgänge asynchron ablaufen.

So verwenden Sie Ereignisziele in Verbindung mit Ihren Abonnements:

  1. Erstellen Sie einen Webhook-Endpoint in Ihrer App.
  2. Fügen Sie Logik zur Verarbeitung von Stripe Ereignissen hinzu. Bei Abonnements umfassen dies fehlgeschlagene Zahlungen und Änderungen des Abonnementstatus (z. B. das Wechseln von einer Testversion in einen aktiven Status).
  3. 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.

Erfahren Sie, wie Sie Ereignisziele einrichten und verwenden. Alternativ können Sie den Webhook-Schnellstart verwenden, um einen minimalen Webhook-Endpoint zu erstellen.

Subscription events

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.

customer.createdWird gesendet, wenn eine Kundin/ein Kunde erfolgreich erstellt wird.
customer.subscription.createdWird beim Erstellen des Abonnements gesendet. Der status des Abonnements kann incomplete lauten, wenn zum Abschließen der Zahlung eine Kundenauthentifizierung erforderlich ist oder wenn Sie payment_behavior auf default_incomplete festlegen. Zeigen Sie das Zahlungsverhalten für Abonnements an, um mehr zu erfahren.
customer.subscription.deletedWird gesendet, wenn das Abonnement eines/einer Kund/in endet.
customer.subscription.pausedWird gesendet, wenn sich der status eines Abonnements in paused ändert. Dies wird beispielsweise gesendet, wenn ein Abonnement so konfiguriert wird, dass es pausiert wird, wenn ein kostenloser Testzeitraum ohne Zahlungsmethode endet. Das Invoicing erfolgt erst nach der Wiederaufnahme des Abonnements. Wir senden dieses Ereignis nicht, wenn der Zahlungseinzug angehalten wird, da in diesem Zeitraum weiterhin Rechnungen erstellt werden.
customer.subscription.resumedWird gesendet, wenn ein Abonnement, das sich zuvor im Status paused befand, wieder aufgenommen wird. Dies gilt nicht, wenn die Pause des Zahlungseinzugs aufgehoben wurde.
customer.subscription.trial_will_endWird drei Tage vor Ablauf des Testzeitraums gesendet. Wenn der Testzeitraum kürzer als drei Tage ist, wird dieses Ereignis ausgelöst.
customer.subscription.updatedWird gesendet, wenn ein Abonnement gestartet oder geändert wird. So lösen beispielsweise das Erneuern des Abonnements, das Hinzufügen eines Gutscheins, das Anwenden eines Rabatts, das Hinzufügen eines Rechnungspostens und das Ändern von Abonnementplänen alle dieses Ereignis aus.
entitlements.active_entitlement_summary.updatedWird gesendet, wenn die aktiven Berechtigungen einer Kundin/eines Kunden aktualisiert werden. Wenn Sie dieses Ereignis erhalten, können Sie den Zugriff auf die Funktionen Ihres Produkts gewähren oder deaktivieren. Mehr erfahren über die Integration mit Berechtigungen.
invoice.createdWird gesendet, wenn eine Rechnung für ein neues oder verlängertes Abonnement erstellt wird. Wenn Stripe keine erfolgreiche Antwort auf invoice.created erhält, verzögert sich die Finalisierung aller Rechnungen mit dem automatischen Einzug um bis zu 72 Stunden. Erfahren Sie mehr über das Finalisieren von Rechnungen.
invoice.finalizedWird gesendet, wenn eine Rechnung erfolgreich finalisiert wurde und bereit für die Bezahlung ist.
  • Sie können die Rechnung an den Kunden/die Kundin senden. Sehen Sie sich die Finalisierung der Rechnung an, um mehr zu erfahren.
  • Je nach Ihren Einstellungen belasten wir automatisch die Standard-Zahlungsmethode oder versuchen den Einzug. Zeigen Sie E-Mails nach der Finalisierung an, um mehr zu erfahren.
invoice.finalization_failedDie Rechnung konnte nicht finalisiert werden. Erfahren Sie in diesem Leitfaden, wie Sie mit Fehlern bei der Rechnungsfinalisierung umgehen. Erfahren Sie im Leitfaden mit der Übersicht zu Rechnungen mehr über die Rechnungsfinalisierung.
  • Überprüfen Sie den last_finalization_error der Rechnung, um die Ursache des Fehlers zu ermitteln.
  • Wenn Sie Stripe Tax verwenden, überprüfen Sie das Feld automatic_tax des Invoice-Objekts.
  • Wenn automatic_tax[status]=requires_location_inputs kann die Rechnung nicht finalisiert werden, und Zahlungen können nicht eingezogen werden. Benachrichtigen Sie Ihre/n Kund/in und erfassen Sie den erforderlichen Kundenstandort.
  • Wenn automatic_tax[status]=failed wiederholen Sie die Anfrage später noch einmal.
invoice.paidWird gesendet, wenn die Rechnung erfolgreich bezahlt wird. Sie können den Zugriff auf Ihr Produkt gewähren, wenn Sie dieses Ereignis erhalten und der status des Abonnements active ist.
invoice.payment_action_requiredWird gesendet, wenn die Rechnung eine Kundenauthentifizierung erfordert. Erfahren Sie, wie Sie mit dem Abonnement umgehen, wenn die Rechnung Maßnahmen erfordert.

invoice.payment_failed

Eine Zahlung für eine Rechnung ist fehlgeschlagen. Der PaymentIntent-Status ändert sich in requires_action. Der Status des Abonnements ist weiterhin incomplete nur für die erste Rechnung des Abonnements. Wenn eine Zahlung fehlschlägt, gibt es zahlreiche Aktionen, die durchgeführt werden können:

invoice.upcomingWird ein paar Tage vor der Verlängerung des Abonnements gesendet. Die Anzahl der Tage basiert auf der im Dashboard festgelegten Anzahl für Bevorstehende Verlängerungsereignisse. Bei bestehenden Abonnements wird die Änderung der Anzahl der Tage im nächsten Abrechnungszeitraum wirksam. Sie können bei Bedarf noch zusätzliche Rechnungsposten hinzufügen.
invoice.updatedWird gesendet, wenn eine Zahlung erfolgreich ist oder fehlschlägt. Wenn die Zahlung erfolgreich ist, wird das Attribut paid auf true festgelegt und der status ist paid. Wenn die Zahlung fehlschlägt, wird das Attribut paid auf false festgelegt und der status bleibt open. Fehlgeschlagene Zahlungen lösen außerdem das Ereignis invoice.payment_failed aus.
payment_intent.createdWird gesendet, wenn ein PaymentIntent erstellt wird.
payment_intent.succeededWird gesendet, wenn die Zahlung für einen PaymentIntent erfolgreich abgeschlossen wurde.
subscription_schedule.abortedWird gesendet, wenn ein Abonnementplan storniert wurde, weil das zugehörige Abonnement aufgrund von Zahlungsverzug gekündigt wurde.
subscription_schedule.canceledWird gesendet, wenn ein Abonnementplan gekündigt wird, wodurch auch alle aktiven zugehörigen Abonnements gekündigt werden.
subscription_schedule.completedWird gesendet, wenn alle Phasen eines Abonnementplans abgeschlossen sind.
subscription_schedule.createdWird gesendet, wenn ein neuer Abonnementplan erstellt wird.
subscription_schedule.expiringWird 7 Tage vor Ablauf eines Abonnementplans gesendet.
subscription_schedule.releasedWird gesendet, wenn ein Abonnementplan freigegeben wird oder beendet und von dem verbleibenden Abonnement getrennt wird.
subscription_schedule.updatedWird gesendet, wenn ein Abonnementplan aktualisiert wird.

Handle payment failures

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.

EreignisBeschreibung

invoice.payment_failed

Eine Zahlung für eine Rechnung ist fehlgeschlagen. Der Status des PaymentIntent ändert sich in requires_payment_method. Der Status des Abonnements ändert sich in incomplete. Wenn eine Zahlung fehlschlägt, gibt es zahlreiche Maßnahmen, die ergriffen werden können:

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

Handle payments that require additional action

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.

EreignisBeschreibung
invoice.finalization_failedDie Rechnung konnte nicht finalisiert werden. Erfahren Sie in diesem Leitfaden, wie Sie mit Fehlern bei der Rechnungsfinalisierung umgehen. Erfahren Sie im Leitfaden mit der Übersicht zu Rechnungen mehr über die Rechnungsfinalisierung.
  • Überprüfen Sie den last_finalization_error der Rechnung, um die Ursache des Fehlers zu ermitteln.
  • Wenn Sie Stripe Tax verwenden, überprüfen Sie das Feld automatic_tax des Invoice-Objekts.
  • Wenn automatic_tax[status]=requires_location_inputs kann die Rechnung nicht finalisiert werden und Zahlungen können nicht eingezogen werden. Benachrichtigen Sie Ihre Kundin/Ihren Kunden und erfassen Sie den erforderlichen Kundenstandort.
  • Wenn automatic_tax[status]=failed wiederholen Sie die Anfrage später noch einmal.

invoice.payment_failed

Eine Zahlung für eine Rechnung ist fehlgeschlagen. Der PaymentIntent-Status ändert sich in requires_action. Der Status des Abonnements ändert sich in incomplete. Wenn eine Zahlung fehlschlägt, gibt es zahlreiche Maßnahmen, die ergriffen werden können:

invoice.payment_action_required

Eine Zahlung für eine Rechnung ist fehlgeschlagen. Der PaymentIntent-Status ändert sich in requires_action. Der Status des Abonnements ändert sich in incomplete. Wenn eine Zahlung fehlschlägt, gibt es zahlreiche Maßnahmen, die ergriffen werden können:

Track active subscriptions

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

Catch subscription status changes

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.

StatusBeschreibung
trialingThe subscription is currently in a trial period and you can safely provision your product for your customer. The subscription transitions automatically to active when a customer makes the first payment.
activeThe subscription is in good standing and the most recent payment is successful. You can safely provision your product for your customer.
incompleteThe customer must make a successful payment within 23 hours to activate the subscription. Or the payment requires action, such as customer authentication. Subscriptions can also be incomplete if there’s a pending payment and the PaymentIntent status is processing.
incomplete_expiredThe initial payment on the subscription failed and the customer didn’t make a successful payment within 23 hours of subscription creation. These subscriptions don’t bill customers. This status exists so you can track customers that failed to activate their subscriptions.
past_duePayment on the latest finalized invoice either failed or wasn’t attempted. The subscription continues to create invoices. Your subscription settings determine the subscription’s next state. If the invoice is still unpaid after all attempted smart retries, you can configure the subscription to move to canceled, unpaid, or leave it as past_due. To move the subscription to active, pay the most recent invoice before its due date.
canceledThe subscription was canceled. During cancellation, automatic collection for all unpaid invoices is disabled (auto_advance=false). This is a terminal state that can’t be updated.
unpaidThe latest invoice hasn’t been paid but the subscription remains in place. The latest invoice remains open and invoices continue to generate, but payments aren’t attempted. Revoke access to your product when the subscription is unpaid because payments were already attempted and retried while past_due. To move the subscription to active, pay the most recent invoice before its due date.
pausedThe subscription has ended its trial period without a default payment method and the trial_settings.end_behavior.missing_payment_method is set to pause. Invoices are no longer created for the subscription. After attaching a default payment method to the customer, you can resume the subscription.

Webhooks und Rechnungen

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.

EreignisBeschreibung
invoice.createdDie Rechnung wurde erfolgreich erstellt und kann nun finalisiert werden. Lesen Sie die Dokumentation, um mehr über die Finalisierung von Rechnungen zu erfahren.
invoice.finalizedDie Rechnung wurde erfolgreich finalisiert und kann jetzt bezahlt werden.
  • Sie können die Rechnung an den Kunden/die Kundin senden. Erfahren Sie mehr über die Rechnungsfinalisierung.
  • Je nach Ihren Einstellungen belastet Stripe automatisch die Standardzahlungsmethode oder versucht, die Zahlung einzuziehen. Erfahren Sie mehr über E-Mails nach der Finalisierung.
invoice.finalization_failedDie Rechnung konnte nicht finalisiert werden. Erfahren Sie in diesem Leitfaden, wie Sie mit Fehlern bei der Rechnungsfinalisierung umgehen. Erfahren Sie im Leitfaden mit der Übersicht zu Rechnungen mehr über die Rechnungsfinalisierung.
  • Überprüfen Sie den last_finalization_error der Rechnung, um die Ursache des Fehlers zu ermitteln.
  • Wenn Sie Stripe Tax verwenden, überprüfen Sie das Feld automatic_tax des Invoice-Objekts.
  • Wenn automatic_tax[status]=requires_location_inputs kann die Rechnung nicht finalisiert werden und Zahlungen können nicht eingezogen werden. Benachrichtigen Sie Ihre Kundin/Ihren Kunden und erfassen Sie den erforderlichen Kundenstandort.
  • Wenn automatic_tax[status]=failed wiederholen Sie die Anfrage später noch einmal.

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.

Testing

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.

Siehe auch

War diese Seite hilfreich?
JaNein
Benötigen Sie Hilfe? Kontaktieren Sie den Kundensupport.
Nehmen Sie an unserem Programm für frühzeitigen Zugriff teil.
Schauen Sie sich unseren Produkt-Changelog an.
Fragen? Sales-Team kontaktieren.
Unterstützt von Markdoc