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

Integrieren Sie das Kundenportal mit der API

Erfahren Sie, wie Sie das Kundenportal mit der Stripe-API integrieren.

Mit dem Kundenportal bieten Sie Ihren Kund/innen Verwaltung von Abonnements, Abrechungs- und Rechnungsdetails, ohne sie selbst entwickeln zu müssen. Nachdem Sie das Portal konfiguriert und integriert haben, werden Kund/innen zu einem Dashboard mit Co-Branding weitergeleitet. Dort können sie ihr Konto verwalten und Funktionen nutzen, die Sie vorher konfiguriert haben.

So integrieren Sie Ihre Anwendung in das Kundenportal:

  1. Konfigurieren Sie die Funktionen und die Nutzeroberfläche (UI) des Portals. Dies können Sie im Dashboard tun.
  2. Implementieren Sie eine Weiterleitung, um das Portal in Ihre Anwendung zu integrieren.
  3. Überwachen Sie Webhooks, um bei Änderungen an Kundenabonnements und Zahlungsmethoden informiert zu werden.
  4. Gehen Sie live, um das Portal in Ihrer Produktionsumgebung zu verwenden.

Oder klonen Sie eines unserer Beispielprojekte:

Sie können Portalsitzungen optional so anpassen, dass unterschiedliche Funktionen je nach Kundin/Kunde zur Verfügung stehen.

Konfigurieren Sie das Portal

Zunächst müssen Sie sich für ein Stripe-Konto registrieren.

Bevor Sie das Kundenportal integrieren, definieren Sie im Dashboard, was Ihre Nutzer/innen mit dem Portal tun können. Wählen Sie Ihre Einstellungen für Sandboxes und den Live-Modus basierend auf Ihrem Produkt- und Preiskatalog.

Häufiger Fehler

Wenn Sie das Kundenportal in Verbindung mit Stripe Connect nutzen, müssen Sie darauf achten, dass Sie das Kundenportal für die Plattform und nicht für ein verbundenes Konto konfigurieren.

Wenn Sie mehrere Portalkonfigurationen für verschiedene Kundengruppen erstellen möchten (oder wenn Sie eine Connect-Plattform haben und die Konfigurationen für Ihre verbundenen Konten verwalten möchten), können Sie dafür die API nutzen:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node
Go
.NET
No results
curl https://api.stripe.com/v1/billing_portal/configurations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "features[invoice_history][enabled]"=true

Produktkatalog einrichten

Wenn Sie Kundinnen und Kunden gestatten, Upgrades oder Downgrades durchzuführen oder die Mengen ihrer Abonnements zu ändern, müssen Sie auch einen Produktkatalog einrichten. Dazu gehören die Produkte und Preise, auf die Ihre Kundinnen und Kunden ein Upgrade oder Downgrade durchführen können, sowie die Abonnements, für die sie Mengen aktualisieren können. Weitere Informationen zum Erstellen von Produkten und Preisen finden Sie unter Produkt erstellen. Wenn Sie das Kundenportal nur für die Rechnungsstellung verwenden, müssen Sie keinen Produktkatalog erstellen.

Das Portal zeigt die folgenden Attribute Ihres Produktkatalogs an:

  • Name und Beschreibung des Produkts: Diese Attribute können im Dashboard und über die API bearbeitet werden.
  • Mengenbeschränkungen pro Produkt: Diese Attribute sind im Dashboard bearbeitbar.
  • Preis, Währung und Abrechnungsintervall: Diese Attribute sind fest und werden nur einmal bei der Erstellung im Dashboard und in der API festgelegt.

Erfassung von Steuer-IDs aktivieren

Wenn Sie Stripe Tax verwenden, um automatisch Steuern für Abonnements oder Rechnungen einzuziehen, können Sie Kundinnen/Kunden erlauben, ihre Steuer-IDs im Kundenportal festzulegen und zu aktualisieren. Stripe Billing fügt die Steuer-IDs zu den Rechnungen der Kundinnen/Kunden hinzu. Damit Kundinnen/Kunden ihre Steuer-IDs selbst festlegen können, gehen Sie zu den Kundenportaleinstellungen und aktivieren Sie Steuer-ID. Weitere Informationen finden Sie unter „So funktionieren Kunden-Steuer-IDs mit Abonnements und Rechnungen“.

Hier erfahren Sie, wie Sie Stripe Tax einrichten, Steuern für wiederkehrende Zahlungen erheben, Steuern in Ihren nutzerdefinierten Zahlungsabläufen einziehen und Steuersätze für Posten und Rechnungen festlegen.

Vorschau und Test

Klicken Sie beim Konfigurieren Ihrer Einstellungen auf Vorschau, um eine Vorschau des Portals anzuzeigen. Dadurch wird eine schreibgeschützte Version des Portals geöffnet, die es Ihnen ermöglicht, zu sehen, wie Ihre Kundinnen und Kunden ihre Abonnements und Rechnungsdetails verwalten können.

Nachdem Sie Ihre Einstellungen gespeichert haben, können Sie das Portal starten und es mit einer Kundin oder einem Kunden in einer Sandbox testen. Gehen Sie im Dashboard auf eine Kundin oder einen Kunden, klicken Sie auf Aktionen, und wählen Sie dann Kundenportal öffnen.

Sie können eine Vorschau des Portals nur als schreibgeschützte Version anzeigen, wenn sich Ihr Dashboard in einer Sandbox befindet. Wenn Sie keine Vorschau des Portals anzeigen und testen können, überprüfen Sie Ihre Einstellungen, um sicherzustellen, dass Ihre Konfiguration in einer Sandbox gespeichert ist. Damit die Vorschau und das Testen funktionieren, müssen Sie auch über die Berechtigung zum Bearbeiten im Dashboard verfügen.

Weiterleitung auf Ihrer Seite implementieren
Clientseitig
Serverseitig

Eine Portalsitzung dient als Einstiegspunkt in das Kundenportal. Sie liefert einen eindeutigen, temporären Link zum Portal. Wenn Kund/innen ihre Rechnungen oder Abrechnung verwalten möchten, können Sie eine neue Portalsitzung erstellen und die Kund/innen zur url der Sitzung weiterleiten.

Fügen Sie auf Ihrer Website eine Schaltfläche hinzu, über die die Kund/innen das Portal aufrufen können. Verwenden Sie eine POST-Anfrage, um eine Portalsitzung zu erstellen:

<form method="POST" action="/create-customer-portal-session">
  <button type="submit">Manage billing</button>
</form>

Fügen Sie als Nächstes einen Endpoint hinzu, über den eine Portalsitzung erstellt wird und Ihre Kund/innen weitergeleitet werden. Authentifizieren Sie Kund/innen auf Ihrer Website, bevor Sie Sitzungen für sie erstellen. Zum Erstellen einer Sitzung benötigen Sie die ID der Kundin/des Kunden und eine return_url, die erforderlich ist, falls in der Dashboard-Konfiguration keine Standard-Rückgabe-URL festgelegt ist.

Wenn Sie eine Portalsitzung erstellen, gibt Stripe das portal session object zurück, das die kurzlebige URL der Sitzung enthält, die Ihre Kund/innen für den Zugriff auf das Kundenportal verwenden.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node
Go
.NET
No results
curl https://api.stripe.com/v1/billing_portal/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer={{CUSTOMER_ID}} \
  --data-urlencode return_url="https://example.com/account"

Webhooks abhören
Serverseitig

Wenn der Abonnementumfang geändert oder Abonnements gekündigt werden, müssen Sie sicherstellen, dass die Kund/innen danach nur Zugriff auf die Produkte oder Dienste haben, die sie tatsächlich abonniert haben. Über Webhooks benachrichtigt Stripe Ihre Integration über diese Änderungen. Sehen Sie sich im Event-Objekt die ID für das Abonnement oder die Kundin/den Kunden an, um herauszufinden, für welche Kundin/welchen Kunden das Ereignis gilt.

Stripe benachrichtigt Ihre Integration auch über Webhooks, wenn eine Rechnung bezahlt wird. Sehen Sie sich im Event-Objekt die ID für die Rechnung oder die Kundin/den Kunden an, um herauszufinden, für welche Kundin/welchen Kunden das Ereignis gilt.

Wenn Sie noch keinen Webhook-Endpoint für Stripe eingerichtet haben, können Sie die Dokumentation zu Webhooks von Stripe lesen, um loszulegen und über die beschriebenen Ereignisse informiert zu werden.

EreignisBeschreibung

customer.subscription.updated

Beobachten Sie dies, um Abonnement-Upgrades und -Downgrades zu überwachen. Überprüfen Sie für Upgrades die Eigenschaft subscription.items.data[0].price im Abonnementobjekt, um den Preis zu finden, den der/die Kund/in abonniert hat. Gewähren Sie dann Zugriff auf das neue Produkt. Überprüfen Sie für Downgrades dieselbe Eigenschaft und passen Sie den Zugriff nach Bedarf an oder entziehen Sie ihn.

Wenn eine Kundin/ein Kunde den Preisplan für ein Abonnement innerhalb eines Testabonnements ändert, endet das Testabonnement sofort beim Wechsel zum neuen Preis.

customer.subscription.updatedBeobachten Sie dies, um Änderungen an der Abonnementmenge zu überwachen. Wenn Sie dieses Ereignis erhalten, prüfen Sie das Attribut subscription.items.data[0].quantity, um die Abonnementmenge der Kundin/des Kunden herauszufinden. Gewähren Sie dann Zugriff auf die neue Menge.

customer.subscription.deleted

Beobachten Sie dies, um Abonnementkündigungen zu überwachen. Wenn Sie dieses Ereignis erhalten, entziehen Sie dem/der Kund/in den Zugriff auf das Produkt. Falls das Portal so konfiguriert ist, dass Abonnements zum Ende eines Abrechnungszeitraums gekündigt werden, überwachen Sie auf das Ereignis customer.subscription.updated, um rechtzeitig über Kündigungen informiert zu werden. Wenn cancel_at_period_end auf true gesetzt ist, wird das Abonnement zum Ende des Abrechnungszeitraums gekündigt.

Falls die Kund/innen ihre Meinung ändern, können sie ihre Abonnements vor Ende des Abrechnungszeitraums reaktivieren. In diesem Fall wird das Ereignis customer.subscription.updated übermittelt. Wenn cancel_at_period_end auf false steht, wurde das Abonnement reaktiviert.

payment_method.attachedTritt auf, wenn ein/e Kund/in eine Zahlungsmethode hinzufügt.
payment_method.detachedTritt auf, wenn ein/e Kund/in eine Zahlungsmethode entfernt.
customer.updatedÜberprüfen Sie die Eigenschaft invoice_settings.default_payment_method, um die Zahlungsmethode zu finden, die ein/e Kund/in als neue Standardzahlungsmethode ausgewählt hat. Wenn Sie Abonnements haben, die die Standardzahlungsmethode auf Kundenebene außer Kraft setzen, können Kund/innen diese Außerkraftsetzung entfernen. Überprüfen Sie das Attribut default_payment_method des Abonnements, wenn Sie dieses Ereignis erhalten, um festzustellen, ob die Außerkraftsetzung entfernt wurde. Verwenden Sie diesen Webhook, um alle relevanten Informationen in Ihrer Datenbank zu aktualisieren. Alle Aktualisierungen dürfen nur als Änderungen der Rechnungsinformationen behandelt werden. Verwenden Sie die Rechnungs-E-Mail-Adresse des/der Kund/in nicht als Anmeldedaten.
customer.tax_id.createdTritt auf, wenn Kund/innen ihre Steuer-IDs verwalten. Stripe kann einige Arten von Steuer-IDs validieren. Weitere Informationen finden Sie im Leitfaden zu Steuer-IDs.
customer.tax_id.deletedTritt auf, wenn Kund/innen ihre Steuer-IDs verwalten. Stripe kann einige Arten von Steuer-IDs validieren. Weitere Informationen finden Sie im Leitfaden zu Steuer-IDs.
customer.tax_id.updatedBeobachten Sie dies, um Validierungs-Updates zu Steuer-IDs von Kund/innen zu erhalten. Weitere Informationen finden Sie im Leitfaden zu Steuer-IDs.
billing_portal.configuration.createdTritt auf, wenn eine Konfiguration erstellt wird.
billing_portal.configuration.updatedTritt auf, wenn eine Konfiguration aktualisiert wird.
billing_portal.session.createdTritt auf, wenn eine Portalsitzung erstellt wird.

Live gehen

Testen Sie das Portal, bevor Sie es in den Produktionsbetrieb integrieren. Führen Sie folgende Schritte aus, wenn Sie bereit für das Go-Live sind:

Wenn Sie eine Portalsitzung erstellen, gibt Stripe das portal session-Objekt zurück, das die kurzlebige URL der Sitzung enthält, die Ihre Kundinnen/Kunden für den Zugriff auf das Kundenportal verwenden müssen. Sie können auch einen gemeinsam nutzbaren Link für jede Konfiguration des Portals mit dem Parameter login_page erstellen.

  • Deaktivieren Sie Testdaten anzeigen im Dashboard.
  • Konfigurieren Sie das Portal im Live-Modus.
  • Fügen Sie die Webhooks im Live-Modus hinzu.

Stripe maintains multiple distinct sets of portal configurations: one for live mode and one for each sandbox. To help you validate your integration, making changes in one mode doesn’t affect your configuration in the other.

War diese Seite hilfreich?
JaNein