Verwendung von OAuth mit Express-KontenVeraltet

Verwenden Sie den OAuth-Verbindungsvorgang, um einem/einer Express-Nutzer/in zu erlauben, sich mit Ihrer Plattform zu verbinden.

Vorsicht

Für neue Connect-Plattformen ist OAuth nicht verfügbar. Verwenden Sie für neue Konten stattdessen die Accounts API mit Express. Extensions sollten Express OAuth nicht verwenden, da diese keine Verbindung zu bestehenden Express-Konten herstellen können. Wenn Sie OAuth für Express-Konten benötigen, kontaktieren Sie bitte unseren Support.

Der OAuth-Verbindungsvorgang

Ein/e Nutzer/in verbindet sich mithilfe des OAuth-Verbindungsvorgangs mit Ihrer Plattform:

Auf einer Seite auf Ihrer Website aus geben Sie einen Link an, der Ihre/n Nutzer/in an Stripe weiterleitet und dabei wird die client_id Ihrer Plattform weitergegeben.
Auf der Website von Stripe stellt der/die Nutzer/in die Informationen bereit, die erforderlich sind, um sich mit Ihrer Plattform zu verbinden.
Stripe leitet den/die Nutzer/in zusammen mit einem Autorisierungscode auf Ihre Seite um.
Ihre Seite führt dann eine Anfrage an den OAuth-Token-Endpoint von Stripe aus, um die Verbindung abzuschließen und die Konto-ID des Nutzers/der Nutzerin abzurufen.

Nach Abschluss all dieser Schritte, können Sie für den/die Nutzer/in API-Anfragen mit seiner/ihrer Konto-ID stellen.

Schritt 1: Sie geben den OAuth-Link an

Gehen Sie zu Ihren Plattformeinstellungen, um Ihre Integration zu starten und:

Ermöglichen Sie das Onboarding von Express-Konten mit OAuth in den OAth-Einstellungen.
Kopieren Sie Ihre client_id, eine einmalige von Stripe generierte Kennung für Ihre Plattform.
Legen Sie Ihren redirect_uri fest, die URL, auf die Ihre Nutzer/innen umgeleitet werden, nachdem sie ihr Konto verbunden haben. Sie müssen alle Weiterleitungs-URLs in Ihren Plattformeinstellungen angeben. Wenn Sie den Parameter redirect_uri nicht in Ihre Anfrage aufnehmen, verwendet Stripe standardmäßig die erste Adresse, die Sie in Ihren Plattformeinstellungen konfiguriert haben.

Stripe stellt außerdem eine Entwickler-client_id bereit, um beim Testen zu helfen.

Mit diesen beiden Informationen können Sie nun den OAuth-Link erstellen. Wir empfehlen, eine Connect-Schaltfläche anzuzeigen, die die Nutzer/innen an unseren Express-OAuth-Endpoint sendet.

https://connect.stripe.com/express/oauth/authorize?redirect_uri=https://connect.stripe.com/connect/default/oauth/test&client_id=ca_FkyHCg7X8mlvCUdMDao4mMxagUfhIwXb&state={STATE_VALUE}

Um CSRF-Angriffe zu verhindern, fügen Sie den Parameter state, dessen Wert auf einen einmaligen Token festgelegt ist, hinzu. Stripe nimmt diesen state-Wert in die Umleitungs-URL auf und sendet den/die Nutzer/in zurück auf Ihre Seite. Bestätigen Sie anschließend, dass dieser state-Parameter denselben Wert hat, den Sie ursprünglich angegeben haben.

So können Sie die Beispiel-URL zusammen mit unserer Verbinden mit Stripe-Schaltfläche präsentieren:

Verbinden mit

Express mithilfe von OAuth-Parametern anpassen

Sie können das Verhalten des Express-Onboarding-Vorgangs ändern, indem Sie zusätzliche URL-Parameter in Ihrem OAuth-Link einfügen. Eine vollständige Liste verfügbarer Parameter finden Sie in der OAuth-Referenz.

Einzel- oder Unternehmenskonten

Sie können angeben, ob Stripe ein Onboarding-Formular für Express für Einzelpersonen oder Unternehmen bereitstellen soll, indem Sie den Parameter stripe_user[business_type] auf individual oder company einstellen.

Stripe erhebt die korrekten Informationen für jeden Kontotyp. Für das Onboarding eines Unternehmens ist zum Beispiel Folgendes erforderlich:

https://connect.stripe.com/express/oauth/authorize?redirect_uri=https://connect.stripe.com/connect/default/oauth/test&client_id=ca_FkyHCg7X8mlvCUdMDao4mMxagUfhIwXb&state={STATE_VALUE}&stripe_user[business_type]=company

Formularfelder vorab ausfüllen

Sie können einige Formularfelder in der Stripe-Anwendung des Nutzers/der Nutzerin vorab ausfüllen, indem Sie die relevanten URL-Parameter in Ihren OAuth-Link einfügen.

In diesem Beispiel wird die E-Mail-Adresse des Nutzers/der Nutzerin mit stripe_user[email] ausgefüllt:

https://connect.stripe.com/express/oauth/authorize?redirect_uri=https://connect.stripe.com/connect/default/oauth/test&client_id=https://connect.stripe.com/connect/default/oauth/test&state={STATE_VALUE}&stripe_user[email]=user@example.com

Funktionen für ein Konto festlegen

Sie können die Funktionen, die auf Ihre neuen verbundenen Konten angewendet werden, in den Dashboard-Einstellungen für Express hinzufügen oder ändern. Wenn Sie jedoch von jedem Ihrer verbundenen Konten unterschiedliche Funktionen anfordern möchten, können Sie den Parameter suggested_capabilities[] in Ihren OAuth-Link einfügen und die Dashboard-Einstellungen auf der Express-Konfigurationsseite überschreiben.

Ein Beispiel für die Funktion transfers

https://connect.stripe.com/express/oauth/authorize?redirect_uri=https://connect.stripe.com/connect/default/oauth/test&client_id=ca_FkyHCg7X8mlvCUdMDao4mMxagUfhIwXb&state={STATE_VALUE}&suggested_capabilities[]=transfers

Stripe fügt diesem Express-Konto die vorgeschlagene Funktion hinzu, es sei denn, eine der folgenden Bedingungen wird erfüllt:

Wenn der/die Nutzer/in sich in einem Land befindet, das keine transfers unterstützt, versucht Stripe, das Konto als card_payments zu kennzeichnen.
Wenn der/die Nutzer/in weder transfers noch card_payments unterstützt, kennzeichnet Stripe das Konto als „Ohne Funktionen“.

Sie können mithilfe des Parameters assert_capabilities[] bestätigen, dass Stripe die vorgeschlagene Funktion hinzugefügt hat. Dieser Schritt ist optional.

Schritt 2: Der/die Nutzer/in erstellt sein/ihr Konto

Wenn die Nutzer/innen den Link auf Ihrer Seite anklicken, werden sie zur Website von Stripe geleitet. Dort werden sie aufgefordert, Kontakt- und Auszahlungsinformationen.

Stripe-Website, auf der Nutzer/innen ihre Kontakt- und Auszahlungsinformationen bereitstellen können

Um den Onboarding-Vorgang zu testen, können Sie (000) 000-0000 als Telefonnummer angeben. Statt eine SMS oder eine E-Mail zu senden, lässt Stripe Sie die Verifizierung mit dem Code 000-000 abschließen.

Express zeigt Ihr Branding im Onboarding-Ablauf und im Express-Dashboard an. Im Abschnitt Connect-Einstellungen Ihres Dashboards können Sie den Namen, das Logo und die optionale Markenfarbe angeben.

Schritt 3: Stripe leitet den/die Nutzer/in auf Ihre Seite zurück

Nachdem ein/e Nutzer/in den Onboarding-Prozess abgeschlossen hat, wird er/sie mit der als die redirect_uri gekennzeichnete URL auf Ihre Seite weitergeleitet.

Bei erfolgreicher Verbindung enthält die Weiterleitungs-URL folgende Werte:

Der Wert state, falls angegeben.
Ein Autorisierungscode. Der Autorisierungscode gilt nur kurze Zeit und kann in der im nächsten Schritt beschriebenen POST-Anfrage nur einmalig verwendet werden.

https://connect.stripe.com/connect/default/oauth/test?code={AUTHORIZATION_CODE}

Schritt 4: Sie schließen die Verbindung des Express-Kontos ab

Fügen Sie den angegebenen Autorisierungs-code in einer POST-Anfrage an den Token-Endpoint von Stripe ein, um die Verbindung abzuschließen und die Konto-ID des Nutzers/der Nutzerin abzurufen:

Stripe gibt eine Antwort zurück, die die Konto-ID (stripe_user_id) für den/die Nutzer/in enthält.

{
  "livemode": false,
  "token_type": "bearer",
  "stripe_user_id": "{{CONNECTED_ACCOUNT_ID}}"
,
  "scope": "express",
  ...
}

Falls ein Problem auftritt, gibt Stripe eine detaillierte Fehlermeldung zurück:

{
  "error": "invalid_grant",
  "error_description": "Authorization code does not exist: {AUTHORIZATION_CODE}"
}

Der/die Nutzer/in ist jetzt mit Ihrer Plattform verbunden. Die stripe_user_id ist die Stripe-Konto-ID für das neue Konto. Speichern Sie diesen Wert in Ihrer Datenbank und verwenden Sie ihn für die Authentifizierung als das verbundene Konto, indem Sie ihn an die Anfragen im Stripe-Account-Header übergeben.

Notiz

Speichern Sie stripe_user_id, die ID des Kontos. Plattformen benötigen diesen Wert (beginnend mit acct_), um Gelder zu übertragen und Anfragen im Auftrag des Nutzers/der Nutzerin durchzuführen.

Funktion des Kontos festlegen

Wenn Sie den Parameter suggested_capabilities[] angeben, können Sie den Parameter assert_capabilities[] hinzufügen, um zu verifizieren, dass das verbundene Konto jetzt über die vorgeschlagenen Funktionen verfügt. Sie können dies zum Beispiel überprüfen, wenn Sie sich über URL-Sicherheit Gedanken machen. Dieser Schritt ist jedoch optional. Stripe handhabt jeden Fehler beim Anwenden einer Funktion im Hintergrund.

Eine Erfolgsmeldung sieht dann folgendermaßen aus:

{
  "livemode": false,
  "token_type": "bearer",
  "stripe_user_id": "{{CONNECTED_ACCOUNT_ID}}"
,
  "scope": "express",
  "capabilities": "transfers",
  ...
}

Wenn der Wert der angegebenen capabilities[] nicht passt, sieht die Fehlermeldung folgendermaßen aus:

{
  "error": "invalid_request",
  "error_description": "assert_capabilities expects capability: card_payments"
}

Der häufigste Grund für das Fehlschlagen dieser Anfrage ist, dass die angegebene Funktion im Land Ihres/Ihrer Nutzer/in nicht verfügbar ist. Weniger wahrscheinlich ist, dass jemand die URL mutwillig ändert.

Webhooks

Nachdem Sie ein Konto erstellt haben, können alle Benachrichtigungen über Änderungen an dem Konto als account.updated-Ereignisse an Ihre Webhooks übergeben werden. Sie können Ihre Connect-Webhook-URL in Ihren Kontoeinstellungen einstellen. Mit diesen Ereignissen können Sie das Onboarding und den Verifizierungsstatus Ihrer verbundenen Konten nachprüfen. Dies kann hilfreich sein, wenn Sie Nutzer-Support bereitstellen und entsprechende Hinweise in der Benutzeroberfläche Ihrer Plattform anzeigen. Alternativ kann Stripe Ihre Nutzer/innen Schritt für Schritt durch den Onboarding- und Verifizierungsprozess führen und sich um alle auftretenden Probleme kümmern.

Wenn Sie im Testmodus entweder mithilfe des Testmodus-API-Schlüssels oder der client_id ein Konto erstellt haben, sendet Stripe keine E-Mails während Sie Ihre Stripe-Integration entwickeln. (Wir tun das erst, wenn Sie live sind.)