Ein Plugin zu einer OAuth 2.0-App migrieren

So migrieren Sie Ihr Plugin über Stripe Apps zur OAuth-Authentifizierung.

Verwenden Sie dieses Handbuch, um Ihr Plugin zu einer Stripe-App zu migrieren, die OAuth 2.0 für die Authentifizierung verwendet, auch bekannt als OAuth 2.0-App.

Zuvor hat es Stripe Plugins gestattet, die Standard-API-Schlüssel eines Nutzers/einer Nutzerin anzufordern, um sich mit deren Produkten zu vernetzen. Ab dem 30. September 2024 verlangt Stripe von allen Plugin-Entwicklern/Entwicklerinnen, dass sie sichere Authentifizierungsmethoden (eingeschränkte API-Schlüssel, OAuth 2.0 oder Stripe Connect) verwenden, um die Nutzer/innen vor Betrug zu schützen. Alle vorhandenen und neuen Plugin-Entwickler/innen müssen eine dieser sicheren Autorisierungsmethoden verwenden. Die Migration Ihres Plugins auf eine OAuth 2.0-App erfüllt diese Anforderung.

Weitere Informationen zu OAuth 2.0 finden Sie unter OAuth 2.0 für Stripe Apps.

Bevor Sie loslegen

Lesen Sie den Abschnitt Ein Plugin zu Stripe Apps oder Stripe Connect migrieren.
Wenn Sie Stripe Connect verwenden und ein vorhandenes Plugin über Stripe Apps migrieren möchten, müssen Sie ein neues Stripe-Konto erstellen. Derzeit kann ein Stripe-Konto mit aktiviertem Connect keine App veröffentlichen.
Sie können pro Konto nur eine öffentliche App erstellen. Wenn Ihr Konto bereits über eine öffentliche App verfügt und Sie eine weitere veröffentlichen möchten, müssen Sie ein neues Stripe-Konto erstellen. Sie können weiterhin mehrere private Apps gleichzeitig mit der öffentlichen App auf demselben Konto erstellen.

Stripe-CLI-Plugin installieren

Melden Sie sich beim Stripe-Dashboard an.
Sofern noch nicht geschehen, installieren Sie die Stripe-CLI und melden Sie sich mit demselben Konto an.
Command Line
Homebrew
# Install Homebrew to run this command: https://brew.sh/ brew install stripe/stripe-cli/stripe # Connect the CLI to your dashboard stripe login
Weitere Installationsoptionen finden Sie unter Mit der Stripe-CLI loslegen.
Stellen Sie sicher, dass Sie CLI Version 1.12.4 oder neuer verwenden. Sie können dies überprüfen, indem Sie Folgendes ausführen:
Command Line
```
stripe version
```
Wenn Ihrer Stripe-CLI-Version älter als 1.12.4 ist, führen Sie eine Aktualisierung auf die neueste Stripe-CLI-Version durch.
Stellen Sie sicher, dass der Knoten installiert und auf dem neuesten Stand ist.
Command Line
```
node -v
```
Sie können die Abhängigkeiten Ihrer App mit NPM oder Yarn verwalten. Verwenden Sie unbedingt die neueste stabile Version. Wenn Sie Ihre App im App Marketplace veröffentlichen möchten gelten zusätzliche Einschränkungen:
- Sie benötigen ein aktiviertes Konto.
- Sie können eine App nicht in einem Connect-fähigen Stripe-Konto veröffentlichen.

Ihre App entwickeln

Installieren Sie das CLI-Plugin für Stripe-Apps: Um mit der Erstellung einer Stripe-App zu beginnen, installieren Sie das CLI-Plugin für Stripe-Apps:
Command Line
```
stripe plugin install apps
```
Wenn Sie das apps-Plugin bereits installiert haben, überprüfen Sie, ob Sie Version 1.5.12 oder höher verwenden.
Command Line
```
stripe apps -v
# apps version 1.5.12
```
Wenn Sie das apps-Plugin aktualisieren müssen, können Sie Folgendes ausführen:
Command Line
```
stripe plugin upgrade apps
```
Erstellen Sie Ihre Stripe-App, indem Sie `stripe apps create <app-name> in der CLI ausführen:
- Bei der Benennung Ihrer App verbietet Stripe die folgenden Begriffe: Authenticator, RAK, Generator, RAK Auth, App, Generator-App, Stripe.
- Im Folgenden finden Sie einige Beispiele für akzeptable Namen: Analytics Pro von DataWiz, Invoice Manager von PayFlow.
- Wenn Sie eine App für einen Drittanbieter entwickeln, verwenden Sie die folgende Namenskonvention: [App-Funktionalität] von [Entwicklername]. Zum Beispiel: Hubspot Sync von Boomi.
Bearbeiten Sie die folgenden Felder im App-Manifest:
- Legen Sie stripe_api_access_type auf oauth fest.
- Legen Sie distribution_type auf public fest.
- Legen Sie Ihre allowed_redirect_uris. Dies sind die URLs, an die Sie Ihre Nutzer/innen weiterleiten, nachdem Sie Ihre App über OAuth installiert haben. Die erste in der Liste ist die Standardweiterleitung.
Beispiel:
Command Line
```
{
  "id": "<YOUR_APP_ID>",
  "version": "0.0.1",
  "name": "Your Stripe App",
  "icon": "./[YOUR_APP]_icon_32.png",
  "permissions": [
    // Your app permissions here
  ],
  "stripe_api_access_type": "oauth",
  "distribution_type": "public",
  "allowed_redirect_uris": [
    // Your redirect URIs here
  ]
}
```
Fügen Sie mit dem Befehl stripe apps grant permission "PERMISSION_NAME" "EXPLANATION" alle Berechtigungen hinzu, die Ihre App benötigt.
(Optional) Fügen Sie Erweiterungen der Nutzeroberfläche zu Ihrer App hinzu. Wir empfehlen, eine Einstellungsansicht hinzuzufügen, damit Ihre Nutzer/innen Einstellungen konfigurieren oder einen Link zur Dokumentation Ihrer App erstellen können. Wenn der einzige Zweck Ihrer App die Authentifizierung ist, entfernen Sie jeglichen unnötigen Code zu Nutzeroberfläche und Nutzererlebnis. Dies trägt dazu bei, dass sich Ihre App auf ihre Hauptfunktion konzentriert.
Laden Sie Ihre App mithilfe des Befehls stripe apps upload in Stripe hoch. Nachdem Sie Ihre OAuth 2.0-App hochgeladen haben, können Sie die API-Authentifizierungsmethode nicht mehr ändern.
Konfigurieren Sie OAuth 2.0 für die Arbeit mit Ihrer App und Ihrem OAuth-Anbieter.
- Stellen Sie sicher, dass Sie den richtigen OAuth-Installationslink verwenden, um den OAuth-Ablauf für Ihre Nutzer/innen zu starten.
- Sie müssen eine Callback-URL in Ihrem App-Manifest angeben, die den OAuth-Autorisierungscode empfangen kann.
- Sie müssen Ihren geheimen Schlüssel verwenden, um den Autorisierungscode für den OAuth-Zugriff auszutauschen und die Token zu aktualisieren, die für das Konto des Nutzers/der Nutzerin gelten.
- Sie müssen das Aktualisierungs-Token regelmäßig verwenden, um ein neues Zugriffs-Token zu erhalten, damit Ihre Nutzer/innen sich nicht jedes Mal authentifizieren müssen, wenn ihr Zugriffs-Token abläuft.

Ihre App testen

Sie können Ihre OAuth-App in Ihrem eigenen Konto oder mit anderen Konten testen:

Wählen Sie im Dashboard für Entwickler/innen > Apps die App aus, die Sie extern testen möchten.
Klicken Sie auf der Detailseite der App auf die Registerkarte Externer Test und dann auf Jetzt starten.
- Wenn die Registerkarte Externer Test nicht angezeigt wird, überprüfen Sie, ob Sie unter Veröffentlichung erstellen die öffentliche Verteilung ausgewählt haben.
Füllen Sie die folgenden Felder aus, um externe Tests zu konfigurieren (die Sie jederzeit bearbeiten können):
- Link-Zugriff: Wählen Sie aus, ob alle oder nur eingeladene Nutzer/innen die App über den Link installieren können.
- Version: Wählen Sie aus, welche Version die Nutzer/innen installieren können. Wenn Sie die Version ändern, wird für alle aktuellen Nutzer/innen eine Aktualisierung auf die neue Version vorgenommen.
Kopieren Sie den Autorisierungslink im Abschnitt OAuth testen. Senden Sie diesen Link an Nutzer/innen, um die App in ihrem Konto zu installieren. Diese Nutzer/innen müssen über Administratorrechte verfügen, um die App installieren zu können. Nachdem ein/e Nutzer/in die Testversion Ihrer App installiert hat, können alle Mitglieder des Kontos diese verwenden.

Weitere Informationen zu externen Tests finden Sie unter App extern testen.

Veröffentlichen und verbreiten Sie Ihre App

So veröffentlichen Sie Ihre App im Stripe App Marketplace:

App zur Prüfung vorlegen.
Nachdem Stripe Ihre App genehmigt hat, veröffentlichen Sie Ihre App im Stripe App Marketplace.

So verteilen Sie Ihre App:

Sehen Sie sich Ihre installierten Apps an und klicken Sie auf die App, die Sie verteilen möchten. Klicken Sie auf der Detailseite der App auf die Registerkarte Einstellungen.
Ermitteln Sie den OAuth-Installationslink aus der Zeit, als Sie Ihre App entwickelt haben. Dieser Link ist modusspezifisch. Je nach Use case müssen Sie den Live- oder den Test-Modus angeben.
Verwenden Sie konsequent denselben OAuth-Installationslink für Ihr Produkt und in den Nutzermitteilungen. Einige zu berücksichtigende Beispiele sind:
- Aktualisieren Sie Ihre Dokumentation, um Nutzer/innen anzuweisen, die Stripe OAuth 2.0-App zu installieren und alle Schritte zu entfernen, die sich auf das Kopieren und Einfügen von API-Schlüsseln beziehen.
- Fügen Sie den OAuth-Installationslink zu Ihrem Plugin-Onboarding hinzu, um Nutzer/innen bei der Installation der App zu unterstützen.
- Verwenden Sie den OAuth-Installationslink in der E-Mail-Kommunikation mit den Nutzern/Nutzerinnen, um sie bei der Aktualisierung ihrer bestehenden Installationen zu unterstützen.

Ihre bestehenden Nutzer/innen migrieren

Nachdem Sie Ihr Plugin zu einer Stripe-App migriert haben, müssen Sie Ihre bestehenden Nutzer/innen migrieren. Je nachdem, wie Sie normalerweise mit Ihren Nutzern/Nutzerinnen interagieren, kann die Vorgehensweise unterschiedlich sein. Hier sind einige allgemeine wichtige Schritte, die jedoch für die meisten Plugins gelten:

Benachrichtigen Sie Ihre bestehenden Nutzer/innen, dass sie ihre Verbindung zu Stripe über Ihren OAuth-Installationslink aktualisieren sollen. Dies kann per E-Mail, in der Nutzeroberfläche Ihres Plugins, über produktinterne Benachrichtigungen, in Ihren Versionshinweisen oder auf viele andere Arten geschehen.
Nachdem ein/e Nutzer/in Ihre App installiert und den OAuth-Ablauf abgeschlossen hat, löschen Sie den vorherigen geheimen API-Schlüssel.
Verfolgen Sie den Fortschritt der Nutzermigration. Verfolgen Sie nach Möglichkeit den Fortschritt der Nutzermigrationen. Setzen Sie sich mit Nutzern/Nutzerinnen in Verbindung, die noch nicht migriert sind, um einen reibungslosen Übergang zu gewährleisten.

OptionalDen Systemzustand Ihrer App überwachen und verbessern

Sie können die folgenden Maßnahmen erkunden und umsetzen, um den Zustand Ihrer App proaktiv zu verbessern:

Um Ihre App zu bewerben, können Sie dem Stripe Partner Ecosystem als Teil des Apps Track beitreten. Alle App-Entwickler/innen sind berechtigt, dem Partnerprogramm beizutreten, und Apps, die bestimmte Meilensteine erreichen, können zusätzliche Partnervorteile freischalten, wenn sie sich weiterentwickeln.
Um das Stripe-Dashboard zu erweitern und nutzerdefinierte Funktionen für Ihre Nutzer/innen bereitzustellen, erstellen Sie eine Erweiterung der Nutzeroberfläche.
Verfolgen Sie Ihre App-Analyse, um Einblicke in die Leistung Ihres Eintrags im App-Marktplatz zu erhalten, beispielsweise Nutzerinstallationskennzahlen.

OptionalZahlungen konfigurieren

Wenn Sie eine App entwickeln, mit der Nutzer/innen Zahlungen abwickeln können, lesen Sie diese Richtlinien:

Zahlungsdaten sicher erfassen

Nutzer/innen von Stripe müssen für PCI-Konformität sorgen, die festlegt, wie Kreditkartendaten sicher zu speichern, zu verarbeiten und zu übertragen sind. Bei Nichteinhaltung oder möglichen Verstößen drohen Unternehmen Strafen.

Da Sie API-Aufrufe für Nutzer/innen von Stripe tätigen, müssen Sie Kreditkartendaten sicher mithilfe der clientseitigen Tokenisierung übermitteln. Kundinnen/Kunden übermitteln ihre persönliche Daten über einen Webbrowser oder eine mobile App direkt an Stripe. Im Gegenzug sendet Stripe ein einfaches Token an Sie. So können Ihre Nutzer/innen Kartendaten sicher erfassen, ohne dass sensible Daten auf den Server gelangen.

Wenn Ihr Plugin ein clientseitiges Zahlungsformular im Browser umfasst, empfehlen wir die Verwendung von:

Stripe Elements: Eine Reihe vorgefertigter Komponenten der Nutzeroberfläche zur Einrichtung Ihres Web-Bezahlvorgangs. Es ist als Feature von Stripe.js verfügbar, unserer grundlegenden JavaScript-Bibliothek für die Erstellung von Zahlungsabläufen.
Stripe Checkout: Eine Low-Code-Zahlungsintegration, die ein anpassbares Formular für den Zahlungseinzug erstellt. Sie können Checkout direkt in Ihre Website integrieren oder Kundinnen/Kunden auf eine von Stripe gehostete Zahlungsseite weiterleiten.

Beide Optionen bieten die clientseitige Tokenisierung.

Wenn Ihr Plugin nur in einer Backend-Umgebung betrieben wird, sollten Sie die Nutzer/innen in Ihrer Dokumentation dazu auffordern, die Zahlungsangaben mit Elements oder Checkout zu tokenisieren. Durch die Tokenisierung können Nutzer/innen von Stripe Zahlungen so sicher wie möglich auf unserer Plattform abwickeln.

Express Checkout Element hinzufügen

Das Express Checkout Element bietet eine einzelne Integration für die Annahme von Zahlungen über Ein-Klick-Zahlungsschaltflächen, einschließlich Apple Pay, Google Pay, Link oder PayPal. Diese Integration ermöglicht es Ihnen, mehrere Schaltflächen gleichzeitig anzuzeigen. Kundinnen/Kunden sehen unterschiedliche Zahlungsschaltflächen, je nachdem, was ihre Geräte- und Browser-Kombination unterstützt.

Mehrere Zahlungsmethoden ermöglichen

Stripe unterstützt neben Kreditkarten noch mehrere andere Zahlungsmethoden. Weitere Informationen zu Zahlungsmethoden finden Sie unter Zahlungsmethoden.

Mit der Payment Methods API können Ihre Nutzer/innen Zahlungen mit weiteren Zahlungsmethoden erfassen (beispielsweise Alipay, iDEAL, Sofort). Sie können diese Zahlungsmethoden über einen Integrationspfad hinzufügen.

Prüfen, ob HTTPS aktiviert ist

Wenn Ihr Plugin ein Zahlungsformular in einem Webbrowser anzeigt, muss es prüfen, ob das Formular über HTTPS bereitgestellt wird. Wir verlangen von unseren Nutzer/innen, dass sie HTTPS aktivieren: Zeigen Sie Ihren Nutzer/innen eine eindeutige Fehlermeldung an, wenn sie nicht ausreichend geschützt sind.

Das folgende Beispiel zeigt, wie Sie überprüfen können, ob Ihre Nutzer/innen HTTPS aktiviert haben:

Command Line
// This example uses Express
const express = require('express');
const app = express();

app.get('/', function(request, response) {
 if (!request.secure) {
   // Present an error to the user
 }
});


app.listen(3000);

Wenn Ihr Plugin eine Frontend-Komponente hat, prüfen Sie, ob HTTPS vom Browser verwendet wird. Mit JavaScript sähe das z. B. so aus:

Command Line
// This example checks for HTTPS from the browser
if (window.location.protocol !== "https:") {
 // Present an error to the user
}