Connect OAuth-Referenz

Diese Referenz enthält verfügbare öffentliche Methoden für unsere OAuth-Endpoints für Connect.

Mit dem OAuth Connect-Prozess können Sie die Nutzererfahrung anpassen, indem Sie zusätzliche Parameter an Stripe übergeben. Einige gängige Beispiele werden unten erklärt, und der Rest der Referenz führt alle möglichen Optionen auf.

Notiz

Denken Sie daran, dass die Daten, die Sie als Plattform für ein Standard-Konto erstellen (d. h. Zahlungen, Kund/innen, Rechnungen usw.) in den Stripe-Konten sichtbar sind. Wenn diese sich mit anderen Plattformen verbinden, haben diese Plattformen und Erweiterungen ebenfalls Zugriff auf diese Daten.

Ab Juni 2021 werden Plattformen, die OAuth im Umfang read_write verwenden, keine Verbindung zu Konten herstellen können, die von einer anderen Plattform kontrolliert werden.

Für Extensions wird es keine Änderungen am Verhalten von OAuth geben. Erfahren Sie hier mehr zu OAuth-Änderungen für Standard-Plattformen.

Gängige Beispiele

Felder vorab ausfüllen

Bieten Sie Nutzer/innen, die ein neues Stripe-Konto erstellen müssen, die bestmögliche Erfahrung, indem Sie die Felder des Kontoformulars mit Informationen, die Sie bereits haben, wie E-Mail und Name des/der Nutzer/in, vorab ausfüllen. Das Vorabausfüllen ist nicht sinnvoll, wenn Ihr/e Nutzer/in bereits über ein Stripe-Konto verfügt. Bestimmte Felder können nicht vorab ausgefüllt werden, einschließlich der Zustimmung zu den Nutzungsbedingungen und dem RISA-Einverständnis in Japan.

Dynamisches Festlegen des Umleitungs-URI

Aus Sicherheitsgründen leitet Stripe eine/n Nutzer/in nur an einen vorab definierten URI weiter. Mit Connect können Sie jedoch mehr als einen Umleitungs-URI definieren, der verwendet werden kann, um die Nutzererfahrung weiter zu personalisieren. Sie könnten beispielsweise einige Ihrer Nutzer/innen zurück an https://sub1.example.com und andere an https://sub2.example.com umleiten lassen.

Dynamisches Festlegen des Umleitungs-URI:

Fügen Sie jeden Weiterleitungs-URI in Ihren Plattformeinstellungen hinzu.
Fügen Sie den Parameter redirect_uri zu Ihrer Autorisierungsanfrage hinzu und legen Sie den Wert auf einen Ihrer Umleitungs-URIs fest.

https://connect.stripe.com/oauth/authorize?response_type=code&client_id={{CLIENT_ID}}&scope=read_write&redirect_uri=https://sub2.example.com

Wenn kein redirect_uri in der URL angegeben ist, verwendet Stripe den ersten URI, der in Ihren Plattformeinstellungen konfiguriert wurde.

Das Konto autorisieren

Für Standard-Konten: GET https://connect.stripe.com/oauth/authorize

Sendet den/die Nutzer/in an Stripe, um eine Verbindung zu Ihrer Plattform herzustellen.

Anfrage

Parameter	Beschreibung
`client_id`	Die eindeutige Kennung, die Ihrer Anwendung übergeben wurde und in Ihren Anwendungseinstellungen zu finden ist.
`response_type`	Derzeit ist Code die einzige Option.
`redirect_uri`Optional	Die URL für die Weiterleitung der Autorisierungsantwort. Falls angegeben, muss dies genau mit einem der durch Kommas getrennten `redirect_uri`-Werte in Ihren Anwendungseinstellungen übereinstimmen. Um sich vor bestimmten Formen von Man-in-the-Middle-Angriffen zu schützen, muss der Live-Modus-`redirect_uri` eine sichere HTTPS-Verbindung verwenden. Standardmäßig wird `redirect_uri` in Ihren Anwendungseinstellungen verwendet, falls nicht angegeben.
`scope`OptionalStandard Only	read_write oder read_only, je nach erforderlicher Berechtigung. Für Standard-Konten ist read_only der Standard. Beachten Sie, dass read_only nur für Erweiterungen angegeben werden kann.
`state`Optional	Ein willkürlicher Zeichenfolgenwert, den wir an Sie zurückgeben, der für den Schutz vor CSRF-Angriffen nützlich ist.

Die folgenden Parameter für Abfragezeichenfolgen sind alle optional. Wir werden sie verwenden, um Details im Kontoformular für neue Nutzer/innen vorab auszufüllen. Einige vorab ausgefüllte Felder (zum Beispiel URL oder Produktkategorie) werden möglicherweise automatisch ausgeblendet. Alle Parameter mit ungültigen Werten werden im Hintergrund ignoriert.

Beachten Sie, dass einige dieser Parameter nur für Standard-Konten gelten (dies ist jeweils angegeben).

Parameter	Beschreibung
`stripe_user[email]`Recommended	Die E-Mail-Adresse des Nutzers/der Nutzerin. Muss ein gültiges E-Mail-Format sein.
`stripe_user[url]`Recommended	Die URL für das Unternehmen des Nutzers/der Nutzerin. Dabei kann es sich um seine/ihre Website, eine Profilseite innerhalb Ihrer Anwendung oder ein anderes öffentlich zugängliches Profil für das Unternehmen handeln, z. B. ein LinkedIn- oder Facebook-Profil. Muss URL-codiert sein und ein Schema (http oder https) enthalten. Wenn Sie dieses Feld vorab ausfüllen, fügen Sie der verlinkten Seite eine Beschreibung der Produkte oder Dienstleistungen des Nutzers/der Nutzerin sowie seine/ihre Kontaktinformationen hinzu. Wenn uns nicht ausreichend Informationen vorliegen, müssen wir den/die Nutzer/in direkt kontaktieren, bevor wir Auszahlungen veranlassen können.
`stripe_user[country]`	Ländercode mit zwei Buchstaben (zum Beispiel US oder CA). Muss ein Land sein, das derzeit von Stripe unterstützt wird.
`stripe_user[phone_number]`	Die Telefonnummer des Unternehmens. Darf höchstens 10 Ziffern enthalten. `stripe_user[country]` muss zudem eine Voreintragung für das entsprechende Land erhalten.
`stripe_user[business_name]`	Der rechtsgültige Name des Unternehmens.
`stripe_user[business_type]`	Die Art des Unternehmens. Für Standard-Konten muss der Wert sole_prop, corporation, non_profit, partnership oder llc sein.
`stripe_user[first_name]`	Vorname der Person, die das Stripe-Anmeldeformular ausfüllt.
`stripe_user[last_name]`	Nachname der Person, die das Stripe-Anmeldeformular ausfüllt.
`stripe_user[dob_day]` `stripe_user[dob_month]` `stripe_user[dob_year]`	Tag (0-31), Monat (1-12) und Jahr (JJJJ, später als 1900) für das Geburtsdatum der Person, die das Stripe-Anmeldeformular ausfüllt. Wenn Sie diese Parameter übergeben möchten, müssen Sie alle drei übergeben.
`stripe_user[street_address]`Standard only	Straßenanschrift in der Adresse des Unternehmens.
`stripe_user[city]`Standard only	Postleitzahl in der Adresse der Stadt. Muss eine Zeichenfolge sein. Um Missverständnisse zu vermeiden, sollten Sie auch `stripe_user[country]` für das entsprechende Land eintragen.
`stripe_user[state]`Standard only	Bundesstaat in der Adresse des Unternehmens. Muss der Code eines US-Bundesstaats oder einer kanadischen Provinz sein (zum Beispiel NY für ein US-Unternehmen oder AB für eines in Kanada). Für `stripe_user[country]` muss zudem das entsprechende Land eingetragen werden.
`stripe_user[zip]`Standard only	Postleitzahl in der Adresse des Unternehmens. Muss eine Zeichenfolge sein. Um Missverständnisse zu vermeiden, sollten Sie auch `stripe_user[country]` für das entsprechende Land eintragen.
`stripe_user[physical_product]`Standard only	Eine Zeichenfolge: true, wenn der/die Nutzer/in ein physisches Produkt verkauft, andernfalls false.
`stripe_user[product_description]`	Eine Beschreibung der Dienstleistungen oder Waren, für die das Unternehmen Zahlungen entgegennimmt.
`stripe_user[currency]`Standard only	ISO-Code mit drei Buchstaben, der die Währung in Kleinbuchstaben (zum Beispiel usd oder cad) darstellt. Die Kombination aus Land und Währung muss gültig sein und von Stripe unterstützt werden. Für `stripe_user[country]` muss das entsprechende Land eingetragen werden.
`stripe_user[first_name_kana]`	Die Kana-Variante des Nachnamens der Person, die das Stripe-Anmeldeformular ausfüllt. Für `stripe_user[country]` muss JP eingetragen werden, da dieser Parameter nur für Japan relevant ist.
`stripe_user[first_name_kanji]`	Die Kanji-Variante des Nachnamens der Person, die das Stripe-Anmeldeformular ausfüllt. Für `stripe_user[country]` muss JP eingetragen werden, da dieser Parameter nur für Japan relevant ist.
`stripe_user[last_name_kana]`	Die Kana-Variante des Nachnamens der Person, die das Stripe-Anmeldeformular ausfüllt. Für `stripe_user[country]` muss JP eingetragen werden, da dieser Parameter nur für Japan relevant ist.
`stripe_user[last_name_kanji]`	Die Kanji-Variante des Nachnamens der Person, die das Stripe-Anmeldeformular ausfüllt. Für `stripe_user[country]` muss JP eingetragen werden, da dieser Parameter nur für Japan relevant ist.
`stripe_user[gender]`	Das Geschlecht der Person, die ein Stripe-Anmeldeformular ausfüllt. (Die internationalen Richtlinien erfordern entweder männlich oder weiblich). Für `stripe_user[country]` muss JP eingetragen werden, da dieser Parameter nur für Japan relevant ist.
`stripe_user[block_kana]`Standard only	Die Kana-Variante eines Adressblocks. Dieser Parameter ist nur für Japan relevant. Sie müssen `stripe_user[country]` mit JP und `stripe_user[zip]` mit einer gültigen japanischen Postleitzahl vorausfüllen, um diesen Parameter zu verwenden.
`stripe_user[block_kanji]`Standard only	Die Kanji-Variante eines Adressblocks. Dieser Parameter ist nur für Japan relevant. Sie müssen `stripe_user[country]` mit JP und `stripe_user[zip]` mit einer gültigen japanischen Postleitzahl vorausfüllen, um diesen Parameter zu verwenden.
`stripe_user[building_kana]`Standard only	Die Kana-Variante der Adressbildung. Dieser Parameter ist nur für Japan relevant. Sie müssen `stripe_user[country]` mit JP und `stripe_user[zip]` mit einer gültigen japanischen Postleitzahl vorausfüllen, um diesen Parameter zu verwenden.
`stripe_user[building_kanji]`Standard only	Die Kanji-Variante der Adressbildung. Dieser Parameter ist nur für Japan relevant. Sie müssen `stripe_user[country]` mit JP und `stripe_user[zip]` mit einer gültigen japanischen Postleitzahl vorausfüllen, um diesen Parameter zu verwenden.

Antwort

Der Browser des Nutzers/der Nutzerin wird zu Ihrem konfigurierten Weiterleitungs-URI oder dem von Ihnen im Parameter redirect_uri übergebenen Wert zurückgeleitet. Bei erfolgreicher Ausführung erhalten Sie die folgenden Abfrageparameter:

Parameter	Beschreibung
`code`	Ein Autorisierungscode, den Sie im nächsten Aufruf verwenden können, um für Ihre/n Nutzer/in einen Zugriffs-Token anzufordern. Dies kann nur einmal verwendet werden und wird nach 5 Minuten ungültig.
`scope`	read_write oder read_only, je nachdem, was Sie in der ursprünglichen GET-Anfrage übergeben haben.
`state`	Der Wert des Parameters `state`, den Sie in der ursprünglichen GET-Anfrage angegeben haben.

Fehlerantwort

Wenn ein Fehler auftritt, wird der Browser des/der Nutzer/in nicht umgeleitet, außer im Fall von access_denied. Stattdessen werden Fehler in einem JSON-Wörterbuch mit folgenden Feldern zurückgegeben:

Parameter	Beschreibung
`error`	A einzigartiger Fehlercode pro Fehlertyp.
`error_description`	Eine von Menschen lesbare Beschreibung des Fehlers.
`state`	Der Wert des Parameters `state`, den Sie in der ursprünglichen GET-Anfrage angegeben haben.

Fehlercodes

Parameter	Beschreibung
`access_denied`	Nutzer/in hat die Autorisierung verweigert.
`invalid_scope`	Ungültiger `scope`-Parameter angegeben.
`invalid_redirect_uri`	Der angegebene Parameter `redirect_uri` ist entweder eine ungültige URL oder wird von Ihren Anwendungseinstellungen nicht zugelassen.
`invalid_request`	Fehlender `response_type`-Parameter
`unsupported_response_type`	Nicht unterstützter `response_type`-Parameter. Der zurzeit einzige unterstützte `response_type` ist Code.

Verbindung abschließen und Konto-ID anfordern

POST https://connect.stripe.com/oauth/token

Verwenden Sie beides, um einen authorization_code in eine Kontoverbindung umzuwandeln und um mithilfe eines refresh_token einen neuen Zugriffs-Token zu erhalten.

Anfrage

Führen Sie diesen Aufruf mithilfe Ihres geheimen API-Schlüssels als client_secret-POST-Parameter durch:

Wenn Sie einen Autorisierungscode in einen Zugriffs-Token umwandeln, müssen Sie einen API-Schlüssel verwenden, der sich im selben Modus (Live- oder Testmodus) wie der Autorisierungscode befindet. (Der Modus hängt davon ab, ob die verwendete client_id in Produktion oder in Entwicklung war.)

Wenn Sie einen Zugriffs-Token mithilfe eines Aktualisierungs-Tokens anfordern, können Sie entweder einen Test- oder einen Live-API-Schlüssel verwenden, um jeweils ein Test- oder Live-Zugriffs-Token zu erhalten. Jedes vorhandene Zugriffs-Token mit demselben Bereich oder Modus (Live- oder Testmodus) wird widerrufen.

Notiz

Laut OAuth v2 ist dieser Endpoint nicht idempotent. Wenn Sie einen Autorisierungscode mehr als einmal verwenden, wird die Kontoverbindung widerrufen.

Parameter	Beschreibung
`grant_type`	authorization_code, wenn ein Autorisierungscode in einen Zugriffs-Token umgewandelt wird oder refresh_token, wenn mithilfe eines Aktualisieurngs-Tokens ein neuer Zugriffs-Token angefordert wird.
`code` oder `refresh_token`	Der Wert des `code` oder `refresh_token`, je nach `grant_type`.
`scope`Optional	Wenn Sie von einem Aktualisierungs-Token einen neuen Zugriffs-Token anfordern, gilt jeder Umfang, der denselben oder einen geringeren Umfang hat, wie der Aktualisierungs-Token. Hat keine Auswirkung, wenn ein Zugriffs-Token von einem Autorisierungscode angefordert wird. Standardmäßig wird der Umfang des Aktualisierungs-Tokens verwendet.

Antwort

Parameter	Beschreibung
`scope`	Der dem Zugriffs-Token gewährte Umfang, abhängig vom Umfang des Autorisierungscodes und des `scope`-Parameters.
`stripe_user_id`	Die einzigartige ID des Kontos, auf das Ihnen Zugriff genehmigt wurde, als Zeichenfolge.
`livemode`	Gibt an, ob der Plattformzugriff zum Durchführen von Aktualisierungen im Auftrag des verbundenen Kontos Zugriff im Live-Modus umfasst oder auf Aktionen im Test-Modus beschränkt ist. Dies entspricht dem Live-Modus der verwendeten Anwendung, um die OAuth-Anforderung zu autorisieren.
`token_type`	Hat immer den Wert Träger.
`access_token`	Deprecated Verwenden Sie den `Stripe-Account`-Header mit dem Geheimschlüssel Ihrer Plattform (der Anfragen im Namen dieses Stripe-Kontos stellen kann).
`stripe_publishable_key`	Deprecated Verwenden Sie den `Stripe-Account`-Header mit dem veröffentlichenbaren Schlüssel Ihrer Plattform (der Anfragen im Namen dieses Stripe-Kontos stellen kann).
`refresh_token`	Deprecated Kann verwendet werden, um einen neuen Zugriffs-Token mit dem gleichen oder einem geringeren Umfang oder in einem anderen Live-Modus zu erhalten (sofern zutreffend).

Fehlerantwort

Parameter	Beschreibung
`error`	A einzigartiger Fehlercode pro Fehlertyp.
`error_description`	Eine von Menschen lesbare Beschreibung des Fehlers.

Fehlercodes

Parameter	Beschreibung
`invalid_request`	Es wurde (wo erforderlich) kein `code`-, `refresh_token`-, oder `grant_type`-Parameter angegeben.
`invalid_grant`	Dieser Fehler kann durch verschiedene Faktoren ausgelöst werden: `code` existiert nicht, ist abgelaufen, wurde bereits verwendet oder gehört Ihnen nicht `refresh_token` existiert nicht oder gehört Ihnen nicht API-Schlüsselmodus (Live- oder Testschlüssel) stimmt nicht mit dem `code`- oder `refresh_token`-Modus überein
`unsupported_grant_type`	Angegebener Parameter `grant_type` wird nicht unterstützt. Die zurzeit einzigen unterstützten Typen sind authorization_code und refresh_token.
`invalid_scope`	Ungültiger `scope`-Parameter angegeben.
`unsupported_response_type`	Nicht unterstützter `response_type`-Parameter. Der zurzeit einzige unterstützte `response_type` ist Code.

Zugriff auf Konto widerrufen

POST https://connect.stripe.com/oauth/deauthorize

Wird verwendet, um den Zugriff auf ein Konto zu widerrufen.

Notiz

Sie können nur den Zugriff eines Standard-Kontos auf Ihre Plattform widerrufen.

Anfrage

Führen Sie diesen Aufruf mithilfe Ihres geheimen API-Schlüssels als Autorisierungs-Header durch.

Wenn Sie den Zugriff auf ein Konto widerrufen, müssen Sie einen API-Schlüssel verwenden, der dem Modus (Live oder Test) entspricht, der für die Verbindung mit dem Konto verwendet wurde. Verwenden Sie einen API Schlüssel für den Live-Modus, wenn die Verbindung von einer Produktions-client_id erstellt wurde, oder einen Test-API-Schlüssel, wenn die Verbindung von einer Entwicklungs-client_id erstellt wurde.

Parameter	Beschreibung
`client_id`	Die `client_id` der Anwendung, von der Sie das Konto trennen möchten. Das Konto muss mit dieser Anwendung verbunden sein.
`stripe_user_id`	Das Konto, von dem Sie die Verbindung trennen möchten.

Antwort

Parameter	Beschreibung
`stripe_user_id`	Die eindeutige ID des Kontos, für das Sie den Zugriff widerrufen haben, als Zeichenfolge. Dies entspricht der von Ihnen übergebenen `stripe_user_id`. Wenn diese zurückgegeben wird, war der Widerruf erfolgreich.

Fehlerantwort

Parameter	Beschreibung
`error`	Ein eindeutiger Fehlercode pro Fehlertyp.
`error_description`	Eine von Menschen lesbare Beschreibung des Fehlers.

Fehlercodes

Parameter	Beschreibung
`invalid_request`	Es wurde (wo erforderlich) kein Parameter `client_id`- oder `stripe_user_id` angegeben.
`invalid_client`	Dieser Fehler kann durch verschiedene Faktoren ausgelöst werden: `client_id` gehört Ihnen nicht. `stripe_user_id`existiert nicht oder ist nicht mit Ihrer Anwendung verbunden API-Schlüsselmodus (Live- oder Testschlüssel) stimmt nicht mit dem `client_id`-Modus überein `no_deauth_on_controlled_account` – das Konto kann nicht getrennt werden, stattdessen die Rejection API verwenden.