# Integrieren Sie das Kundenportal mit der API Erfahren Sie, wie Sie das Kundenportal mit der Stripe-API integrieren. Wenn Ihre Connect-Plattform verwendet [kundenkonfigurierte Konten](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), benutze unser [Anleitung](https://docs.stripe.com/connect/use-accounts-as-customers.md) Ersetzen `Customer` und Ereignisreferenzen in Ihrem Code mit den entsprechenden Accounts v2 API-Referenzen. 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](https://docs.stripe.com/customer-management/integrate-customer-portal.md#configure) Sie die Funktionen und die Nutzeroberfläche (UI) des Portals. Dies können Sie im Dashboard tun. 1. [Implementieren Sie eine Weiterleitung](https://docs.stripe.com/customer-management/integrate-customer-portal.md#redirect), um das Portal in Ihre Anwendung zu integrieren. 1. [Überwachen Sie Webhooks](https://docs.stripe.com/customer-management/integrate-customer-portal.md#webhooks), um bei Änderungen an Kundenabonnements und Zahlungsmethoden informiert zu werden. 1. [Gehen Sie live](https://docs.stripe.com/customer-management/integrate-customer-portal.md#go-live), um das Portal in Ihrer Produktionsumgebung zu verwenden. Sie können Portalsitzungen optional so [anpassen](https://docs.stripe.com/customer-management/integrate-customer-portal.md#customize), 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](https://dashboard.stripe.com/register/). 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* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes) und den Live-Modus basierend auf Ihrem Produkt- und Preiskatalog. > 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* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients)-Plattform haben und die Konfigurationen für Ihre verbundenen Konten verwalten möchten), können Sie dafür die [API](https://docs.stripe.com/api/customer_portal/configurations/object.md) verwenden: ```curl curl https://api.stripe.com/v1/billing_portal/configurations \ -u "<>:" \ -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](https://docs.stripe.com/products-prices/manage-prices.md#create-product). 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](https://docs.stripe.com/tax.md) 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* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) der Kundinnen/Kunden hinzu. Damit Kundinnen/Kunden ihre Steuer-IDs selbst festlegen können, gehen Sie zu den [Kundenportaleinstellungen](https://dashboard.stripe.com/settings/billing/portal) und aktivieren Sie **Steuer-ID**. Weitere Informationen finden Sie unter „So funktionieren Kunden-Steuer-IDs mit [Abonnements](https://docs.stripe.com/billing/customer/tax-ids.md) und [Rechnungen](https://docs.stripe.com/invoicing/taxes/account-tax-ids.md)“. Hier erfahren Sie, wie Sie [Stripe Tax einrichten](https://docs.stripe.com/tax/set-up.md), [Steuern für wiederkehrende Zahlungen erheben](https://docs.stripe.com/billing/taxes/collect-taxes.md), [Steuern in Ihren nutzerdefinierten Zahlungsabläufen einziehen](https://docs.stripe.com/tax/custom.md#existing-customer) und [Steuersätze für Posten und Rechnungen festlegen](https://docs.stripe.com/tax/invoicing.md). ### 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: ```html
``` 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](https://docs.stripe.com/api/customer_portal/sessions/create.md) 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 `Portalsitzungsobjekt` zurück, das die [kurzlebige URL](https://docs.stripe.com/api/customer_portal/sessions/object.md?lang=curl#portal_session_object-url) der Sitzung enthält, die Ihre Kundinnen und Kunden für den Zugriff auf das Kundenportal verwenden. ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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. Wenn Ihre Kundinnen und Kunden ihre Abrechnungsinformationen im Kundenportal aktualisieren, ist es wichtig, Ihre Kundendaten zu aktualisieren. Überwachen Sie Änderungen mit dem Webhook `customer.updated`. Stripe benachrichtigt Ihre Integration auch über *Webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests), 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](https://docs.stripe.com/webhooks.md) von Stripe lesen, um loszulegen und über die beschriebenen Ereignisse informiert zu werden. | Ereignis | Beschreibung | | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-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](https://docs.stripe.com/billing/subscriptions/trials.md) ändert, endet das Testabonnement sofort beim Wechsel zum neuen Preis. | | [customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.updated) | Beobachten 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](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.deleted) | Listen to this to monitor subscription cancellations. When you receive this event, revoke the customer’s access to the product. If you configure the portal to cancel subscriptions at the end of a billing period, listen to the [customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.updated) event to be notified of cancellations before they occur. For flexible [billing mode](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-billing_mode) subscriptions, if `cancel_at` is not `null`, the subscription is canceled at the end of its billing period. For classic billing mode subscriptions, check that `cancel_at_period_end` is `true`. If a customer changes their mind, they can reactivate their subscription prior to the end of the billing period. When they do this, a [customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.updated) event is sent. For flexible billing mode subscriptions, check that `cancel_at` is `null` to confirm reactivation. For classic billing mode, check that `cancel_at_period_end` is `false`. | | [payment_method.attached](https://docs.stripe.com/api/events/types.md#event_types-payment_method.attached) | Tritt auf, wenn ein/e Kund/in eine Zahlungsmethode hinzufügt. | | [payment_method.detached](https://docs.stripe.com/api/events/types.md#event_types-payment_method.detached) | Tritt auf, wenn ein/e Kund/in eine Zahlungsmethode entfernt. | | [customer.updated](https://docs.stripe.com/api/events/types.md#event_types-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.created](https://docs.stripe.com/api/events/types.md#event_types-customer.tax_id.created) | Tritt 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](https://docs.stripe.com/billing/customer/tax-ids.md). | | [customer.tax_id.deleted](https://docs.stripe.com/api/events/types.md#event_types-customer.tax_id.deleted) | Tritt 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](https://docs.stripe.com/billing/customer/tax-ids.md). | | [customer.tax_id.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.tax_id.updated) | Beobachten Sie dies, um Validierungs-Updates zu Steuer-IDs von Kund/innen zu erhalten. Weitere Informationen finden Sie im [Leitfaden zu Steuer-IDs](https://docs.stripe.com/billing/customer/tax-ids.md). | | [billing_portal.configuration.created](https://docs.stripe.com/api/events/types.md#event_types-billing_portal.configuration.created) | Tritt auf, wenn eine Konfiguration erstellt wird. | | [billing_portal.configuration.updated](https://docs.stripe.com/api/events/types.md#event_types-billing_portal.configuration.updated) | Tritt auf, wenn eine Konfiguration aktualisiert wird. | | [billing_portal.session.created](https://docs.stripe.com/api/events/types.md#event_types-billing_portal.session.created) | Tritt 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 `Portalsitzungsobjekt` zurück, das die [kurzlebige URL](https://docs.stripe.com/api/customer_portal/sessions/object.md?lang=curl#portal_session_object-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](https://docs.stripe.com/api/customer_portal/configurations/object.md#portal_configuration_object-login_page) erstellen. - Deaktivieren Sie **Testdaten anzeigen** im Dashboard. - [Konfigurieren](https://dashboard.stripe.com/settings/billing/portal) Sie das Portal im Live-Modus. - Fügen Sie die [Webhooks](https://dashboard.stripe.com/webhooks) im Live-Modus hinzu. Stripe pflegt mehrere unterschiedliche Sets von Portal-Konfigurationen: eines für den Live-Modus und eines für jede Sandbox. Um Ihnen bei der Validierung Ihrer Integration zu helfen, wirken sich Änderungen in einem Modus nicht auf die Konfiguration im anderen aus. ## Optional: Deep Link zu bestimmten Seiten Möglicherweise möchten Sie Kundenaktionen optimieren und die Arbeitsabläufe zwischen Ihrer eigenen App und Stripe weiter anpassen. Deep-Links im Kundenportal ermöglichen es Ihnen, direkt auf eine Seite zu verlinken, auf der die angegebene Aktion ausgeführt werden kann, und das Weiterleitungsverhalten nach Abschluss der Aktion durch den/die Kund/in anzupassen. Erfahren Sie mehr über die Verwendung von [Deep-Links im Kundenportal](https://docs.stripe.com/customer-management/portal-deep-links.md). ## Optional: Portalsitzung anpassen [Serverseitig] Möglicherweise sollen für verschiedene Kundengruppen verschiedene Produkte, Preise oder Funktionen im Portal zur Verfügung stehen. Wenn Sie für eine Portalsitzung eine bestimmte Konfiguration verwenden möchten, legen Sie fest, dass sie beim Starten des Portals automatisch übernommen werden soll. Andernfalls wird die Standardkonfiguration verwendet. Im Dashboard kann nur die Standardkonfiguration erstellt und geändert werden. Andere Konfigurationen können Sie nur über die [API](https://docs.stripe.com/api/customer_portal/configurations/object.md) verwalten. ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d configuration={{CONFIGURATION_ID}} ``` Wenn Sie eine Connect-Plattform sind, können Sie beim Aufruf des Portals `on_behalf_of` angeben. Dies hat zur Folge, dass das Branding, das Logo und der Unternehmensname der Portalsitzung das `on_behalf_of`-Konto widerspiegeln. Außerdem zeigt das Portal nur Abonnements und Rechnungen mit dem angegebenen `on_behalf_of`-Konto an. Weitere Informationen zu `on_behalf_of` finden Sie in der [on_behalf_of-Dokumentation](https://docs.stripe.com/connect/separate-charges-and-transfers.md#settlement-merchant). ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d configuration={{CONFIGURATION_ID}} \ -d on_behalf_of={{CONNECTED_ACCOUNT_ID}} ``` ## Optional: Branding anpassen So passen Sie das Portal an: 1. Rufen Sie die Seite [Branding-Einstellungen](https://dashboard.stripe.com/settings/branding) auf, laden Sie Ihr Symbol oder Logo hoch und passen Sie die Farben an. 1. Rufen Sie die Seite [Öffentliche Kontoeinstellungen](https://dashboard.stripe.com/settings/public) auf und überprüfen Sie Ihren öffentlichen Unternehmensnamen und die Informationen.