# Connect OAuth-Referenz Diese Referenz enthält verfügbare öffentliche Methoden für unsere OAuth-Endpoints für Connect. Mit dem OAuth *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)-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. > Denken Sie daran, dass die Daten, die Sie als Plattform für ein Standard-Konto erstellen (d. h. Zahlungen, Kund/innen, *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) 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](https://docs.stripe.com/building-extensions.md) wird es keine Änderungen am Verhalten von OAuth geben. Erfahren Sie hier mehr zu [OAuth-Änderungen für Standard-Plattformen](https://docs.stripe.com/connect/oauth-changes-for-standard-platforms.md). ## 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: 1. Fügen Sie jeden Weiterleitungs-URI in Ihren [Plattformeinstellungen](https://dashboard.stripe.com/settings/connect/onboarding-options/oauth) hinzu. 2. 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](https://dashboard.stripe.com/settings/connect/onboarding-options/oauth) zu finden ist. | | `response_type` | Derzeit ist **Code** die einzige Option. | | `redirect_uri`(Optional) | Die URL für die Weiterleitung der [Autorisierungsantwort](https://docs.stripe.com/connect/oauth-reference.md#get-authorize-response). Falls angegeben, muss dies genau mit einem der durch Kommas getrennten `redirect_uri`-Werte in Ihren [Anwendungseinstellungen](https://dashboard.stripe.com/settings/connect/onboarding-options/oauth) ü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`(Optional)(Standard 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](https://docs.stripe.com/connect/oauth-changes-for-standard-platforms.md). | | `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. Einige dieser Parameter gelten nur für Standard-Konten (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](http://en.wikipedia.org/wiki/ISO_4217) 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](https://dashboard.stripe.com/settings/connect/onboarding-options/oauth) 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](https://docs.stripe.com/connect/oauth-reference.md#get-authorize-error-codes) 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](https://dashboard.stripe.com/settings/connect/onboarding-options/oauth) 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: #### curl ```bash curl https://connect.stripe.com/oauth/token \ -u <>: \ -d "code"="ac_123456789" \ -d "grant_type"="authorization_code" ``` 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. > 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 eindeutige ID des Kontos, auf das Sie Zugriff erhalten haben, 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](https://docs.stripe.com/connect/oauth-reference.md#get-authorize). | | `token_type` | Hat immer den Wert **Träger**. | | `access_token` | (Deprecated) Verwenden Sie den `Stripe-Account`-[Header](https://docs.stripe.com/connect/authentication.md#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](https://docs.stripe.com/connect/authentication.md#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](https://docs.stripe.com/connect/testing.md#creating-accounts)). | ### Fehlerantwort | Parameter | Beschreibung | | --- | --- | | `error` | A einzigartiger [Fehlercode](https://docs.stripe.com/connect/oauth-reference.md#post-token-error-codes) 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**. | #### API ## Zugriff auf Konto widerrufen `POST https://connect.stripe.com/oauth/deauthorize` Wird verwendet, um den Zugriff auf ein Konto zu widerrufen. Nach dem Widerruf kann Ihre Plattform nicht mehr über das Dashboard oder die API auf das Konto zugreifen. Das Konto kann weiterhin über das Dashboard des Kontos auf seine eigenen Daten und Funktionen zugreifen. > 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. #### curl ```bash curl https://connect.stripe.com/oauth/deauthorize \ -u <>: \ -d client_id="ca_FkyHCg7X8mlvCUdMDao4mMxagUfhIwXb" \ -d stripe_user_id=acct_ON3nXtRQkhmUIQ ``` 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](https://docs.stripe.com/connect/oauth-reference.md#post-deauthorize-error-codes) 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](https://docs.stripe.com/api/account/reject.md) verwenden. | #### Dashboard ### Konten über das Dashboard entfernen Sie können ein verbundenes Konto über seine Kontodetailseite in Ihrem Dashboard trennen. Klicken Sie oben rechts auf der Seite auf das Überlaufmenü (⋯) und wählen Sie dann **Konto entfernen** aus. Mit dieser Aktion wird das Konto von Ihrer Plattform getrennt und der auf die gleiche Weise wie bei der OAuth-Deautorisierung des Endpoints widerrufen. Wenn Sie ein Konto über das Dashboard von Ihrer Plattform entfernen, werden auch alle Plattform-Steuerungen für das Konto, wie z. B. der Auszahlungszeitpunkt, dauerhaft zurückgesetzt, selbst wenn das Konto später erneut verbunden wird. Ansonsten hat dies keine Auswirkungen auf das Konto, welches weiterhin wie ein normales Stripe-Konto funktioniert.