# Integrieren Sie das Kundenportal mit der API Erfahren Sie, wie Sie das Kundenportal mit der Stripe-API integrieren. Mit dem Kundenportal ermöglichen Sie es Ihren Kundinnen und Kunden, ihre Abonnements, die Abrechnung und Rechnungen zu verwalten, ohne diese Funktionalität selbst entwickeln zu müssen. Verwenden Sie das Dashboard, um zu konfigurieren, auf welche Funktionen Ihre Kundinnen und Kunden zugreifen können, wie z. B. den Wechsel von Abonnementplänen. Erstellen Sie dann eine Portalsitzung und leiten Sie Kundinnen und Kunden an ein von Stripe gehostetes Portal mit Co-Branding weiter, in dem sie ihre Konten verwalten können. ## 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, verwenden Sie das Dashboard, um auszuwählen, welche Aktionen Kundinnen und Kunden ausführen können. Konfigurieren Sie das Portal separat 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 mit Stripe Connect verwenden, konfigurieren Sie es für Ihre Plattform, nicht für ein verbundenes Konto. Um unterschiedliche Portaleinstellungen für verschiedene Gruppen von Kundinnen und Kunden zu verwenden oder Konfigurationen für verbundene Konten als *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 zu verwalten, [erstellen Sie Portalkonfigurationen mit der API](https://docs.stripe.com/api/customer_portal/configurations/create.md): ```curl curl https://api.stripe.com/v1/billing_portal/configurations \ -u "<>:" \ -d "features[invoice_history][enabled]=true" ``` ### Produktkatalog einrichten Wenn Kundinnen und Kunden Upgrades oder Downgrades durchführen oder die Abonnementmengen ändern können, müssen Sie einen Produktkatalog konfigurieren. Geben Sie die Produkte und Preise an, zu denen sie wechseln können, sowie die Abonnementposten, deren Mengen sie ändern können. Weitere Informationen finden Sie unter [Produkt erstellen](https://docs.stripe.com/products-prices/manage-prices.md#create-product). Sie müssen keinen Produktkatalog konfigurieren, wenn Sie das Kundenportal nur für die Rechnungsstellung verwenden. Das Portal zeigt die folgenden Attribute Ihres Produktkatalogs an: - **Produktname und -beschreibung**: Bearbeitbare Attribute im Dashboard und in der API. - **Mengenbeschränkungen pro Produkt**: Bearbeitbare Attribute im Dashboard. - **Preisbetrag, Währung und Abrechnungsintervall**: Feste Attribute. Sie können diese nur festlegen, wenn Sie sie im Dashboard und in der API erstellen. ### 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)“. Weitere Informationen finden Sie unter [Stripe Tax einrichten](https://docs.stripe.com/tax/set-up.md) und [Steuern für wiederkehrende Zahlungen erheben](https://docs.stripe.com/billing/taxes/collect-taxes.md). ### Vorschau und Test Klicken Sie während der Konfiguration des Portals auf **Vorschau**, um eine schreibgeschützte Ansicht zu öffnen und zu sehen, wie Kundinnen und Kunden ihre Abonnements und Abrechnungsdetails verwalten können. Testen Sie das Portal nach dem Speichern Ihrer Einstellungen mit einer Sandbox-Kundin/einem Sandbox-Kunden: 1. Öffnen Sie im Dashboard die Kundendetailseite. 2. Klicken Sie auf **Aktionen**. 3. Klicken Sie auf **Kundenportal öffnen**. Sie können das Portal nur in einer Sandbox in der Vorschau anzeigen und testen, und Sie benötigen Bearbeitungsberechtigungen für das Dashboard. Wenn diese Optionen nicht verfügbar sind, vergewissern Sie sich, dass Sie eine Sandbox anzeigen, die Konfiguration in dieser Sandbox gespeichert haben und über die erforderlichen Berechtigungen 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. > #### Verwenden Sie die Accounts v2 API zum Darstellen von Kundinnen und Kunden > > Die Accounts v2 API ist allgemein für Connect-Nutzer/innen verfügbar und für andere Stripe-Nutzer/innen in der öffentlichen Vorschau. Wenn Sie an der Accounts v2 Vorschau teilnehmen, müssen Sie eine [Vorschauversion](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning) in Ihrem Code angeben. > > Um der Vorschau von Accounts v2 beizutreten, gehen Sie zu [Kontovorschauen und -funktionen](https://dashboard.stripe.com/settings/previews) in Ihrem Dashboard und aktivieren Sie **wiederverwendbare Zahlungsmethoden für Global Payouts**. > > Für die meisten Anwendungsfälle empfehlen wir, [Ihre Kundinnen und Kunden als vom Kunden bzw. von der Kundin konfigurierte Account-Objekte abzubilden](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md), anstatt [Customer](https://docs.stripe.com/api/customers.md)-Objekte zu verwenden. #### Accounts v2 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ --data-urlencode "return_url=https://example.com/account" ``` #### Customers v1 ```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 configurable endpoint that executes when it receives certain event notifications from an event destination) 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 Billing Informationen im Kundenportal aktualisieren, ist es wichtig, Ihre Kunden/Kundinnen zu aktualisieren. Überwachen Sie Änderungen mit dem Webhook `customer/Kundin.updated` oder `v2.core.Account[configuration.custom/Kundin].updated`. Stripe benachrichtigt Ihre Integration auch über *Webhooks* (A configurable endpoint that executes when it receives certain event notifications from an event destination), 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 bei Stripe eingerichtet haben, beachten Sie [Stripe-Webhooks](https://docs.stripe.com/webhooks.md). Überwachen Sie dann die Ereignisse in der folgenden Tabelle. | 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 Kundinnen und Kunden das Portal nutzen, um ein Abonnement mit einer [Testphase](https://docs.stripe.com/billing/subscriptions/trials/free-trials.md) hoch- oder herabzustufen, endet die Testphase des Abonnements 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) | Beobachten Sie dies, um Abonnementkündigungen zu überwachen. Wenn Sie dieses Ereignis erhalten, entziehen Sie der Kundin oder dem Kunden den Zugriff auf das Produkt. Falls das Portal so konfiguriert ist, dass Abonnements zum Ende eines Rechnungsstellungszeitraums gekündigt werden, überwachen Sie das Ereignis [customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.updated), um rechtzeitig über Kündigungen informiert zu werden. Wenn `cancel_at` bei Abonnements im flexiblen [Abrechnungsmodus](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-billing_mode) nicht `null` ist, wird das Abonnement zum Ende des Rechnungsstellungszeitraums gekündigt. Vergewissern Sie sich bei Abonnements mit klassischem Abrechnungsmodus, dass `cancel_at_period_end` `true` ist. Wenn eine Kundin/ein Kunde ihre oder seine Meinung ändert, kann sie/er ihr/sein Abonnement vor dem Ende des Rechnungsstellungszeitraums reaktivieren. In diesem Fall wird ein Ereignis [customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.updated) gesendet. Überprüfen Sie bei Abonnements im flexiblen Abrechnungsmodus, ob `cancel_at` `null` ist, um die Reaktivierung zu bestätigen. Vergewissern Sie sich im klassischen Abrechnungsmodus, dass `cancel_at_period_end` `false` ist. | | [customer.subscription.paused](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.paused) | Tritt auf, wenn ein Abonnement, das eine Kundin oder ein Kunde im Portal `pausiert` hat, den Status „Pausiert“ annimmt. Sperren Sie den Zugriff auf Ihren Dienst, sobald Sie dieses Ereignis erhalten, und nicht erst, wenn die Kundin oder der Kunde die Pause plant. Erfahren Sie, wie Sie mit [Pausen- und Wiederaufnahmeereignissen umgehen](https://docs.stripe.com/customer-management/pause-subscriptions.md#webhooks). | | [customer.subscription.resumed](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.resumed) | Tritt auf, wenn ein pausiertes Abonnement fortgesetzt wird, entweder automatisch oder weil der Kunde/die Kundin es vorzeitig im Portal fortgesetzt hat. Stellen Sie den Zugriff auf Ihren Dienst wieder her, wenn Sie dieses Ereignis erhalten. | | [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) | Tritt auf, wenn ein [Kund/in](https://docs.stripe.com/api/customers/object.md)-Objekt aktualisiert wird. Überprüfen Sie das Attribut `Rechnung_settings.default_zahlung_method`, um die Zahlungsmethode zu finden, die der Kunde/die Kundin als neue Standardzahlungsmethode ausgewählt hat. Wenn Sie Subscriptions haben, die die Standardzahlungsmethode auf Kunden/Kundin Überschreibung setzen, können Kund/innen diese Überschreibung entfernen. Überprüfen Sie das Attribut `default_zahlung_method` des Abos, wenn Sie dieses Ereignis erhalten, um festzustellen, ob die Überschreibung 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 nicht die E-Mail-Adresse des Kunden/der Kundin als Anmeldedaten. | | [v2.core.account[configuration.customer].updated](https://docs.stripe.com/api/v2/core/events/event-types.md#v2_event_types-v2.core.account%5Bconfiguration.customer%5D.updated) | Tritt auf, wenn die Kundenkonfiguration eines von Kund/innen konfigurierten `Kontos` [aktualisiert](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-customer) wird. Überprüfen Sie das Attribut `configuration.customer.billing.default_payment_method`, um die Zahlungsmethode zu finden, die der/die Kund/in als neuen Standard ausgewählt hat. Wenn Sie Abonnements haben, die die Standard-Zahlungsmethode auf Kundenebene überschreiben, können Kund/innen diese Überschreibung entfernen. Überprüfen Sie das Attribut `default_payment_method des Abonnements`, wenn Sie dieses Ereignis erhalten, um zu sehen, ob die Überschreibung 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 nicht die E-Mail-Adresse des/der Kund/in 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. | ## Portal starten Testen Sie das Portal unbedingt, bevor Sie es in der Produktion aktivieren. 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 [Kundenportalkonfigurationen](https://docs.stripe.com/api/customer_portal/configurations/object.md) verwalten. #### Accounts v2 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d configuration={{CONFIGURATION_ID}} ``` #### Customers v1 ```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). #### Accounts v2 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d configuration={{CONFIGURATION_ID}} \ -d on_behalf_of={{CONNECTED_ACCOUNT_ID}} ``` #### Customers v1 ```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. 2. Rufen Sie die Seite [Öffentliche Kontoeinstellungen](https://dashboard.stripe.com/settings/public) auf und überprüfen Sie Ihren öffentlichen Unternehmensnamen und die Informationen.