# Funktionsweise von Erweiterungen Erfahren Sie, wie Sie Stripe mit Erweiterungen anpassen können. Mit Erweiterungen können Sie nutzerdefinierte Logik an bestimmten Stellen in Stripe ausführen, die als [Erweiterungspunkte](https://docs.stripe.com/extensions/extension-points.md) bezeichnet werden. Wenn Stripe die Logik an diesen Erweiterungspunkten ausführen muss, wird überprüft, ob eine Erweiterung verbunden ist, und falls gefunden, wird die nutzerdefinierte Logik in der Erweiterung ausgeführt. Zum Beispiel definiert Stripe einen Erweiterungspunkt für [anteilmäßige Verrechnungen](https://docs.stripe.com/extensions/scripts/build-prorations-extension.md). Wenn Stripe den Schritt zur Berechnung der anteilmäßigen Verrechnung erreicht, führt es die Logik Ihrer Erweiterung anstelle der Standardlogik für die anteilmäßige Verrechnung aus. Ihre Erweiterung bestimmt, wie anteilmäßig verrechnet wird, gibt den Betrag zurück, und Stripe setzt den Abrechnungsablauf mit diesem Ergebnis fort. Stripe definiert außerdem einen Erweiterungspunkt für benutzerdefinierte Aktionen für [Workflows](https://docs.stripe.com/extensions/custom-actions/how-custom-actions-work.md). Wenn ein Workflow ausgelöst wird, ruft Stripe Ihre Erweiterung auf, um eine E-Mail zu senden, ein CRM zu aktualisieren oder eine andere von Ihnen definierte Operation auszuführen. ## Funktionsweise des Modells Stripe definiert Erweiterungspunkte, d. h. bestimmte Stellen in Stripe-Produkten, an denen Ihr Code ausgeführt werden kann. Jeder Erweiterungspunkt gibt Folgendes an: - **Eingabe**: Die Daten, die Stripe beim Erreichen des Erweiterungspunkt an Ihre Erweiterung sendet, einschließlich der von dem/der Nutzer/in der Erweiterung stammenden Eingabe - **Ausgabe**: die Daten, die Ihre Erweiterung an Stripe zurückgeben muss - **Zulässige Implementierungstypen**: Welche Implementierungstypen (Scripts, Remote-Funktionen oder beides) Sie bei diesem Erweiterungspunkt verwenden können (See full diagram at https://docs.stripe.com/extensions/how-extensions-work) ```text [Nutzereingabe] --> [Validierung] [Validierung] --> [Code-Erweiterung] [Stripe-Eingabe] --> [Code-Erweiterung] [Code-Erweiterung] --> [Ausgabe] ``` Suchen Sie zunächst nach dem [Erweiterungspunkt](https://docs.stripe.com/extensions/extension-points.md) für Ihren Use Case. Sie erstellen Ihre nutzerdefinierte Logik als Erweiterung, die sich mit einem Erweiterungspunkt verbindet. Wir verpacken Erweiterungen als Teil von [Stripe Apps](https://docs.stripe.com/stripe-apps.md), die Installation, Berechtigungen und Verteilung übernehmen. Sie können mehrere Erweiterungen mit beliebigem Implementierungstyp in derselben App verpacken: [Scripts](https://docs.stripe.com/extensions/how-extensions-work.md#scripts), [Remote-Funktionen](https://docs.stripe.com/extensions/how-extensions-work.md#remote-functions) oder [Nutzeroberflächenerweiterungen](https://docs.stripe.com/extensions/how-extensions-work.md#ui-extensions). Apps können auch [nutzerdefinierte Objekte](https://docs.stripe.com/custom-objects.md) enthalten. ## Implementierungstypen Jeder Erweiterungspunkt unterstützt einen oder mehrere Implementierungstypen. Der Implementierungstyp bestimmt, wo Ihr Code ausgeführt wird und wie er mit externen Diensten interagiert. ### Implementierungstyp auswählen Wenn ein Erweiterungspunkt sowohl Scripts als auch Remote-Funktionen unterstützt, verwenden Sie diese Tabelle, um Folgendes zu entscheiden: | Abwägung | Script | Remote-Funktion | | --- | --- | --- | | Wo es läuft | Von Stripe verwaltete Laufzeitumgebung | Ihre Infrastruktur | | Sprache | TypeScript | Beliebige Sprache (HTTP-Endpoint) | | Externe API-Aufrufe | Erweiterungspunkt-abhängig. Erlaubt für nutzerdefinierte Aktionen (über `endpointFetch()`). Nicht zulässig für Erweiterungspunkte zur Abrechnung. | Ja, Sie tätigen Aufrufe direkt von Ihren Servern | | Autorisierung für externe Dienste | Stripe fügt Secrets über die Endpoint-Konfiguration und den [Secret Store](https://docs.stripe.com/stripe-apps/store-secrets.md) ein (wo externe API-Aufrufe erlaubt sind) | Sie verwalten die Authentifizierung selbst | | Autorisierung von Stripe für Ihren Code | Hinweis: Ihr Code wird auf Stripe ausgeführt | Stripe signiert jede Anfrage. Sie [verifizieren die Webhook-Signatur](https://docs.stripe.com/webhooks.md#verify-signature). | | Ideal für Folgendes | Logik, die keine eigene Infrastruktur von Ihnen benötigt | Logik, die Ihre eigenen Systeme, Transformationen oder Nicht-TypeScript-Sprachen benötigt | | Einschränkungen | Keine Abhängigkeiten von Drittanbietern, kein roher `fetch()`, nur TypeScript | Sie verwalten Hosting, Verfügbarkeit und Bereitstellung | ### Scripts Scripte sind TypeScript-Methoden, die mit der vollständig verwalteten Laufzeitumgebung von Stripe ausgeführt werden. Sie müssen keine Infrastruktur hosten, da Stripe Ihren Code ausführt und Sie die Bereitstellung durch Hochladen Ihrer App über die Stripe-CLI durchführen. Scripts führen Ihre Unternehmenslogik aus, wenn Stripe einen Erweiterungspunkt erreicht. Verwenden Sie Scripts, wenn Sie: - komplexe Geschäftsregeln unter Verwendung von Code anwenden möchten, beispielsweise die Berechnung eines Rabatts auf Grundlage der Kaufhistorie einer Kundin oder eines Kunden und von Sale-Aktionen. - Daten validieren oder umwandeln möchten, bevor Stripe diese verarbeitet, beispielsweise um zu prüfen, ob eine Kundin oder ein Kunde die Zulassungskriterien erfüllt. - externe Daten in Stripe-Abläufe integrieren möchten, ohne Webhooks erstellen und verwalten zu müssen. - schnell Prototypen erstellen möchten, ohne eigene Dienste bereitstellen und verwalten zu müssen. Was Scripts können, hängt vom Erweiterungspunkt ab: - **Bei Abrechnungs-Erweiterungspunkten** (Kundensaldo, Handhabung von Posten, anteilmäßige Verrechnungen): Scripts können nur Daten von Stripe empfangen, Ihre Logik ausführen und ein Ergebnis zurückgeben. Externe API-Aufrufe sind nicht zulässig. Diese Erweiterungspunkte werden in der Abrechnungs-Pipeline ausgeführt, wo Stripe unerwünschte Auswirkungen eindämmt, um die Zuverlässigkeit aufrechtzuerhalten. - **Am Erweiterungspunkt für benutzerdefinierte Aktionen** (für Workflows): Skripte können mithilfe von `endpointFetch()` externe HTTP-Aufrufe durchführen. Sie deklarieren Endpunkte in Ihrem [App-Manifest](https://docs.stripe.com/stripe-apps/reference/app-manifest.md?manifestVersion=manifest-v2) und Stripe übernimmt die Speicherung von Geheimnissen und das Einfügen der Authentifizierung über den [Secret Store](https://docs.stripe.com/stripe-apps/store-secrets.md). Dies ist für Aktionen konzipiert, die auf externe Dienste zugreifen, ohne dass Sie Infrastruktur verwalten müssen. #### Use Cases | Use Case | Abrechnungsverhalten | Script | Beschreibung | | --- | --- | --- | --- | | Legen Sie einen Mindestbetrag für Abbuchungen fest. | Kundensaldo | [Mindestbetrag vor dem Einzug](https://docs.stripe.com/billing/scripts/stripe-authored/customer-balance.md#minimum-amount-before-collection) | Verwenden Sie dieses Script, um die Einziehung kleiner Rechnungsbeträge zu vermeiden, indem Sie sie auf das Kundenguthaben übertragen, bis die geschuldete Summe einen von Ihnen definierten Schwellenwert erreicht. Dies ist nützlich, wenn Sie Zahlungen über mehrere Abrechnungszyklen hinweg ansammeln möchten, bevor Sie sie einziehen, oder wenn Sie vermeiden möchten, Kundinnen und Kunden Bagatellbeträge in Rechnung zu stellen. | | Legen Sie ein maximales Guthaben fest, das auf eine einzelne Rechnung angewendet werden soll. | Kundensaldo | [Obergrenze für die Gutschrift pro Rechnung](https://docs.stripe.com/billing/scripts/stripe-authored/customer-balance.md#maximum-credit-per-invoice) | Verwenden Sie dieses Script, wenn Sie Gutschriften auf mehrere Abrechnungszyklen verteilen möchten, anstatt sie auf einmal anzuwenden, oder wenn Geschäftsregeln eine Beschränkung der Nutzung von Gutschriften pro Rechnung vorschreiben. | | Führen Sie Positionen für gemessene Nutzung und lizenzierte Positionen auf separaten Rechnungen auf. | Erstellung und Weiterleitung von Rechnungsposten | [Separate Rechnung für nutzungsbasierte Posten](https://docs.stripe.com/billing/scripts/stripe-authored/invoice-item-creation-and-routing.md#separate-invoice-for-metered-items) | Verwenden Sie dieses Script, wenn Ihr Finanzteam Nutzungsgebühren getrennt von wiederkehrenden Gebühren pro Nutzer/in oder Lizenzgebühren abgleichen muss oder wenn Ihre Kundinnen und Kunden andere Rechnungen für sie erwarten. | | Berechnen Sie anteilige Verrechnungen nach Stunden, Tagen, Wochen oder Monaten. | Anteilmäßige Verrechnung | [Nach benutzerdefiniertem Intervall anteilmäßig verrechnen](https://docs.stripe.com/billing/scripts/stripe-authored/proration.md#prorate-by-custom-interval) | Verwenden Sie dieses Script immer dann, wenn Ihr Unternehmen eine anteilmäßige Verrechnung in Einheiten benötigt, die größer als eine Sekunde sind, sei es um regionalen Abrechnungsgepflogenheiten zu entsprechen, sich an vertraglichen Konditionen auszurichten oder durch Bruchteilbeträge ausgelöste Verwirrung der Kundinnen und Kunden zu verhindern. | | Erstatten Sie den vollen Betrag für einige Positionen in einem Abonnement zurück oder buchen Sie diesen ab. | Anteilmäßige Verrechnung | [Vollständigen Produktpreis erstatten und abbuchen](https://docs.stripe.com/billing/scripts/stripe-authored/proration.md#credit-and-debit-full-product-price) | Verwenden Sie dieses Script, wenn bestimmte Produkte eines Abonnements nicht anteilmäßig verrechnet werden. Dies kann beispielsweise für eine pauschale Support-Gebühr oder eine Plattformzugriffsgebühr gelten, die immer vollständig abgerechnet wird, unabhängig davon, wann sich das Abonnement ändert. | | Wenden Sie einen prozentualen Rabatt mit einem Höchstbetrag an. | Rabattberechnung | [Prozentualer Rabatt bis zu einem Höchstbetrag](https://docs.stripe.com/billing/scripts/stripe-authored/discount-calculation.md#percent-off-up-to-maximum) | Verwenden Sie dieses Skript, um einen prozentualen Rabatt anzubieten und gleichzeitig den maximalen Rabattbetrag auf einer Rechnung zu begrenzen. | | Verschenken Sie zusätzliche Einheiten ausgewählter Produkte. | Rabattberechnung | [„Kaufen Sie eins, bekommen Sie eins gratis“-Aktionen und Mengenrabatte](https://docs.stripe.com/billing/scripts/stripe-authored/discount-calculation.md#bogo-and-quantity-promos) | Verwenden Sie dieses Skript für mengenabhängige Werbeaktionen für Produkte, die anhand von Metadaten ausgewählt wurden. | | Wenden Sie einen festen Rabatt auf ausgewählte Preise an. | Rabattberechnung | [Preisgebundener Rabattbetrag](https://docs.stripe.com/billing/scripts/stripe-authored/discount-calculation.md#price-targeted-amount-off) | Verwenden Sie dieses Skript, um einen festen Betrag von den anhand von Metadaten ausgewählten Preisen abzuziehen, ohne dass nicht betroffene Rechnungsposten rabattiert werden. | | Wenden Sie einen prozentualen Rabatt auf ausgewählte Preise an. | Rabattberechnung | [Prozentualer Preisrabatt nach Zielpreis](https://docs.stripe.com/billing/scripts/stripe-authored/discount-calculation.md#price-targeted-percent-off) | Verwenden Sie dieses Skript, um einen prozentualen Rabatt auf Preise anzuwenden, die anhand von Metadaten ausgewählt wurden, ohne dass nicht betroffene Rechnungsposten rabattiert werden. | #### Einschränkungen Die meisten [TypeScript](https://www.typescriptlang.org/docs/handbook/intro.html#get-started)-Funktionen funktionieren zur Laufzeit von Stripe, aber die folgenden Muster sind nicht verfügbar. Die Schritte zum Erstellen und Hochladen fangen diese automatisch ab: - Codeauswertung wie `eval()` oder `new Function()` - Timer-Funktionen wie `setTimeout()`, `setInterval()` und `setImmediate()` - Zugriff auf den globalen Bereich über `global` oder `globalThis` - Prozess-APIs wie `process.exit()` oder `process.env` - `console.log()`. Verwenden Sie [Workbench](https://docs.stripe.com/workbench.md), um die Logs der Script-Ausführung anzuzeigen. - Eingebettete API-Schlüssel oder Geheimnisse. Verwenden Sie zum Verwalten sensibler Werte den [Stripe-Geheimnisspeicher](https://docs.stripe.com/stripe-apps/store-secrets.md). - Netzwerkzugriffs-APIs wie `fetch()`. Verwenden Sie `endpointFetch()`, um [Endpoints aus einem Script aufzurufen](https://docs.stripe.com/extensions/invoke-endpoints.md). Stripe unterstützt derzeit keine Bibliotheken von Drittanbietern als Abhängigkeiten. ### Remote-Funktionen Remote-Funktionen sind HTTP-Endpoints, die Sie auf Ihrer eigenen Infrastruktur hosten. Stripe ruft Ihren Endpoint auf, wenn der Erweiterungspunkt erreicht ist, und signiert jede Anfrage mit einer [Webhook-Signatur](https://docs.stripe.com/webhooks.md#verify-signature), damit Sie überprüfen können, ob sie von Stripe stammt. Sie verwalten die Authentifizierung für alle externen Dienste, die Ihr Code aufruft, Stripe gibt keine Geheimnisse für Remote-Funktionen ein. Sie verifizieren die eingehende Stripe-Signatur und kümmern sich selbst um die ausgehende Autorisierung. Nutzen Sie Remote-Funktionen für Folgendes: - Logik auf Ihren eigenen Servern oder in Ihrer eigenen Umgebung ausführen - In Ihre eigenen Systeme wie ERP oder CRM integrieren - Andere Sprache als TypeScript verwenden #### Einschränkungen Remote-Funktionen weisen derzeit die folgenden Einschränkungen auf: - Sie verwalten Hosting, Verfügbarkeit und Bereitstellung. - Ihre Endpoints müssen innerhalb der durch den Erweiterungspunkt definierten Zeitüberschreitung antworten (zum Beispiel 20 Sekunden für benutzerdefinierte Aktionen). ### Erweiterungen der Nutzeroberfläche React-Komponenten, die im Stripe-Dashboard angezeigt werden. Verwenden Sie eine Nutzeroberflächenerweiterung, um Nutzerinnen und Nutzern im Dashboard eine nutzerdefinierte Nutzeroberfläche anzuzeigen. Siehe [Nutzeroberflächenerweiterungen](https://docs.stripe.com/stripe-apps/how-ui-extensions-work.md). ## Berechtigungen Wenn Sie eine Erweiterung erstellen, müssen Sie die Berechtigungen deklarieren, die Ihre Erweiterung benötigt. Eine Erweiterung kann nur auf die Daten zugreifen, für die ihr die Berechtigung zum Lesen oder Schreiben erteilt wurde. Nutzer/innen von Erweiterungen erteilen diese Berechtigungen bei der Installation der App, die die Erweiterungen enthält. Eine vollständige Liste aller [Berechtigungen](https://docs.stripe.com/stripe-apps/reference/permissions.md) finden Sie hier. ## Verbundene Konten Ihre konfigurierten Erweiterungen gelten nicht für Ihre verbundenen Konten. Verbundene Konten müssen die Erweiterung eigenständig in ihrer installierten App konfigurieren. ## Lifecycle Eine Erweiterung kann diesem Lifecycle folgen. Versionierung, Veröffentlichung, Kennzeichnung als veraltet und Archivierung sind optional: 1. **Erstellen**: Sie erstellen eine Erweiterung innerhalb einer Stripe-App. 2. **Hochladen**: Sie laden die App über die Stripe-CLI hoch. Stripe verarbeitet sie und stellt sie zur Installation bereit. 3. (Optional) **Version**: Sie laden neue Versionen hoch, während Sie iterieren. 4. (Optional) **Veröffentlichen**: Sie teilen die App über einen [externen Testkanal](https://docs.stripe.com/stripe-apps/test-app.md) oder den [Stripe App Marketplace](https://docs.stripe.com/stripe-apps/publish-app.md). Sie wird dann zur Installation in den Konten anderer Nutzer/innen verfügbar. 5. **Installieren**: Sie oder diejenigen, mit denen die App geteilt wird, installieren sie und akzeptieren die zugehörigen Berechtigungen. 6. **Aktivieren**: Der/die App-Nutzer/in aktiviert eine Erweiterung an seinem/ihrem Erweiterungspunkt. 7. **Aufrufen**: Stripe ruft die aktivierte Erweiterung immer dann auf, wenn er den Erweiterungspunkt erreicht. 8. (Optional) [Als veraltet markieren](https://docs.stripe.com/extensions/manage-extension-lifecycle.md): Der/die App-Nutzer/in kann eine Version einer Erweiterung nicht aktivieren, aber Erweiterungen, die bereits für diese Version aktiviert wurden, werden weiterhin ausgeführt. 9. (Optional) [Archivieren](https://docs.stripe.com/extensions/manage-extension-lifecycle.md): Aktivierte Erweiterungen werden auf eine kompatible Version umgestellt oder nicht mehr ausgeführt, wenn keine Version definiert ist. 10. **Deaktivieren**: Der/die App-Nutzer/in deaktiviert die Erweiterung. Sie verbleibt im Konto, wird aber von Stripe nicht mehr aufgerufen, wenn sie den Erweiterungspunkt erreicht. 11. **Deinstallieren**: Der/die App-Nutzer/in entfernt die App und ihre Erweiterungen aus dem Konto. ## Mit dem Erstellen beginnen Wenn Sie sich für Anpassungen der Abrechnung interessieren, beginnen Sie mit der Schritt-für-Schritt-Anleitung: [Erstellen einer Script-Erweiterung für die Abrechnung](https://docs.stripe.com/extensions/scripts/build-prorations-extension.md). Darin werden die Voraussetzungen, die Erstellung der App, CLI-Befehle und das Hochladen behandelt. Welche Anleitung Sie ansonsten befolgen, hängt davon ab, für welchen Erweiterungspunkt Sie die Erweiterung erstellen: - [Erstellen Sie eine Erweiterung des Abrechnungsscripts](https://docs.stripe.com/extensions/scripts/build-prorations-extension.md), um den Kundesaldo, die Handhabung von Posten oder das Verhalten bei der anteiligen Verrechnung anzupassen. - [Erstellen Sie eine nutzerdefinierte Workflow-Aktion mit einem Script](https://docs.stripe.com/extensions/custom-actions/build-with-script.md) oder [Remote-Funktionen](https://docs.stripe.com/extensions/custom-actions/build-with-remote-function.md). Erfahren Sie mehr darüber, [wie nutzerdefinierte Aktionen funktionieren](https://docs.stripe.com/extensions/custom-actions/how-custom-actions-work.md). Eine vollständige Liste der verfügbaren Erweiterungspunkte und ihrer unterstützten Implementierungstypen finden Sie unter [Erweiterungspunkte](https://docs.stripe.com/extensions/extension-points.md).