Connect OAuth-Referenz
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 Umleitungs-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 einzigartige Kennung, die Ihrer Anwendung übergeben wurde, in Ihren Anwendungseinstellungen zu finden. |
response_type | Derzeit ist Code die einzige Option. |
redirect_uri Optional | Die URL zum Weiterleiten der Autorisierungsantwort. Falls angegeben, muss diese 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 Livemodus redirect_uri eine sichere HTTPS-Verbindung verwenden. Falls nicht angegeben, wird standardmäßig der redirect_uri in Ihren Anwendungseinstellungen´ verwendet. |
scope OptionalStandard Only | read_write oder read_only, je nach erforderlichem Zugriffslevel. Für Standard-Konten ist read_only der Standard. |
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/der Nutzer/in. 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/der Nutzer/in 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/der Nutzer/in wird zurück zu Ihrem konfigurierten Weiterleitungs-URI oder dem Wert, den Sie im Parameter redirect_uri
übergeben haben, umgeleitet. Bei Erfolg sollten Sie die folgenden Abfrageparameter erhalten:
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 einen Test- oder Live-Zugriffs-Token zu erhalten. Jeder vorhandene Zugriffs-Token im selben Umfang und 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:
|
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. |