Référence OAuth de Connect

Cette référence répertorie les méthodes publiques disponibles pour nos endpoints OAuth de Connect.

Le flux OAuth de Connect vous permet de personnaliser l’expérience utilisateur en transmettant d’autres paramètres à Stripe. Vous trouverez ci-dessous des exemples typiques, et le reste de la référence répertorie toutes les options possibles.

Remarque

En tant que plateforme, n’oubliez pas que les données créées pour un compte Standard (les paiements, clients, factures, etc.) seront visibles sur le compte Stripe de l’utilisateur. Cela signifie également que si l’utilisateur connecte d’autres plateformes, ces dernières ont aussi accès aux données.

Depuis juin 2021, les plateformes utilisant OAuth avec le périmètre read_write ne peuvent plus se connecter à des comptes contrôlés par une autre plateforme.

Les extensions ne connaîtront aucune modification en termes de fonctionnement du flux OAuth. Découvrez plus d’informations sur les modifications d’OAuth pour les plateformes Standard.

Exemples typiques

Pré-remplir les champs

Fournissez la meilleure expérience utilisateur possible pour les utilisateurs qui nécessitent de créer un nouveau compte Stripe en préremplissant les champs du formulaire du compte avec les informations que vous détenez déjà, telles que l’e-mail et le nom de l’utilisateur. Le préremplissage n’a aucun effet si votre utilisateur a déjà un compte Stripe. Vous ne pouvez pas préremplir certains champs, y compris l’acceptation des conditions d’utilisation du service et l’acceptation du RISA au Japon.

Définir de manière dynamique l’URI de redirection

À des fins de sécurité, Stripe redirige uniquement un utilisateur vers une URI prédéfinie. Cependant, Connect vous permet de définir plus d’une URI de redirection, ce qui peut être utilisé pour personnaliser l’expérience utilisateur. Par exemple, vous pourriez rediriger certains de vos utilisateurs vers https://sub1.example.com et les autres vers https://sub2.example.com.

Pour définir de manière dynamique l’URI de redirection :

Dans les paramètres de votre plateforme, ajoutez chaque URI de redirection.
Ajoutez un paramètre redirect_uri à votre demande d’autorisation et définissez la valeur sur l’une de vos URI de redirection.

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

Si aucune redirect_uri n’est indiquée dans l’URL, Stripe utilise la première URI configurée dans les paramètres de votre plateforme.

Autoriser le compte

Pour les comptes Standard : GET https://connect.stripe.com/oauth/authorize

Envoie l’utilisateur vers Stripe pour qu’il se connecte à votre plateforme.

Requête

Paramètre	Description
`client_id`	L’identificateur unique fourni à votre application, qui se trouve dans les paramètres de votre application.
`response_type`	La seule option pour le moment est code.
`redirect_uri`Facultatif	L’URL de redirection de la réponse d’autorisation. Si elle est fournie, elle doit correspondre exactement à l’une des valeurs `redirect_uri` séparées par une virgule dans les paramètres de votre application. Pour vous protéger de certaines formes d’attaques d’intercepteurs, l’URL `redirect_uri` en mode production doit utiliser une connexion HTTPS sécurisée. Elle est définie par défaut sur `redirect_uri` dans les paramètres de votre application si elle n’est pas fournie.
`scope`FacultatifStandard uniquement	read_write ou read_only, en fonction du niveau d’accès dont vous avez besoin. Par défaut, les comptes Standard sont en read_only. Notez que read_only peut uniquement être spécifié pour les extensions.
`state`Facultatif	Une valeur d’une chaîne arbitraire qui vous sera renvoyée, elle sera utile pour la protection CSRF.

Les paramètres de la chaîne de requête suivants sont tous facultatifs, nous les utilisons pour préremplir les informations dans le formulaire du compte pour les nouveaux utilisateurs. Certains champs préremplis (par exemple, l’URL ou la catégorie de produit) peuvent être automatiquement cachés. Les paramètres avec des valeurs non valides sont ignorés.

Notez que certains de ces paramètres s’appliquent uniquement aux comptes Standard (indiqués).

Paramètre	Description
`stripe_user[email]`Recommandé	L’adresse e-mail de l’utilisateur. Doit avoir un format d’e-mail valide.
`stripe_user[url]`Recommandé	L’URL pour l’entreprise de l’utilisateur. Il peut s’agir du site Web de l’utilisateur, une page de profil au sein de votre application, ou un autre profil disponible pour tous, comme un profil LinkedIn ou Facebook. Doit être encodé dans l’URL et inclure un schéma (http ou https). Si vous pré-renseignez ce champ, ajoutez une description des produits ou services de l’utilisateur et ses informations de contact dans les pages liées. Si nous n’avons pas suffisamment d’informations, nous devrons contacter l’utilisateur directement avant d’initier les virements.
`stripe_user[country]`	Code pays à deux lettres (par exemple, US ou CA). Doit être un pays actuellement pris en charge par Stripe.
`stripe_user[phone_number]`	Numéro de téléphone de l’entreprise. Doit contenir 10 chiffres uniquement. `stripe_user[country]` doit également être pré-renseigné avec le pays correspondant.
`stripe_user[business_name]`	Dénomination sociale de l’entreprise.
`stripe_user[business_type]`	Le type d’entreprise. Pour les comptes Standard, la valeur doit être l’une des suivantes : sole_prop, corporation, non_profit, partnership ou llc.
`stripe_user[first_name]`	Prénom de la personne qui remplit une inscription Stripe.
`stripe_user[last_name]`	Nom de la personne qui remplit une inscription Stripe.
`stripe_user[dob_day]` `stripe_user[dob_month]` `stripe_user[dob_year]`	Jour (0-31), mois (1-12) et année (AAAA, supérieure à 1900) pour la date de naissance de la personne qui remplit une inscription Stripe. Si vous choisissez de ne pas compléter ces paramètres, aucun des trois ne doit être complété.
`stripe_user[street_address]`Standard uniquement	Adresse de l’entreprise.
`stripe_user[city]`Standard uniquement	Ville de l’adresse de l’entreprise. Pour éviter toute ambiguïté, préremplissez aussi `stripe_user[country]` avec le pays correspondant.
`stripe_user[state]`Standard uniquement	État de l’adresse de l’entreprise. Il doit s’agir d’un code d’État ou de province à deux lettres (par exemple, NY pour une entreprise des États-Unis ou AB pour une entreprise du Canada). `stripe_user[country]` doit également être prérempli avec le pays correspondant.
`stripe_user[zip]`Standard uniquement	Code postal de l’adresse de l’entreprise. Obligatoirement une chaîne. Pour éviter toute ambiguïté, préremplissez aussi `stripe_user[country]` avec le pays correspondant.
`stripe_user[physical_product]`Standard uniquement	Une chaîne : true si l’utilisateur vend un produit physique, sinon false.
`stripe_user[product_description]`	Une description de ce pour quoi l’entreprise accepte les paiements.
`stripe_user[currency]`Standard uniquement	Code ISO à trois lettres représentant la devise, en minuscules (par exemple, usd ou cad). Doit être une combinaison pays-devise valide prise en charge par Stripe. `stripe_user[country]` doit également être prérempli avec le pays correspondant.
`stripe_user[first_name_kana]`	La variation Kana du prénom de la personne qui remplit une inscription Stripe. Doit pré-renseigner `stripe_user[country]` avec JP, car ce paramètre est uniquement pertinent pour le Japon.
`stripe_user[first_name_kanji]`	La variation Kanji du prénom de la personne qui remplit une inscription Stripe. Doit pré-renseigner `stripe_user[country]` avec JP, car ce paramètre est uniquement pertinent pour le Japon.
`stripe_user[last_name_kana]`	La variation Kana du nom de famille de la personne qui remplit une inscription Stripe. Doit pré-renseigner `stripe_user[country]` avec JP, car ce paramètre est uniquement pertinent pour le Japon.
`stripe_user[last_name_kanji]`	La variation Kanji du nom de famille de la personne qui remplit une inscription Stripe. Doit pré-renseigner `stripe_user[country]` avec JP, car ce paramètre est uniquement pertinent pour le Japon.
`stripe_user[gender]`	Le genre de la personne qui remplit une inscription Stripe (les règlementations internationales exigent soit homme soit femme). Doit pré-renseigner `stripe_user[country]` avec JP, car ce paramètre est uniquement pertinent pour le Japon.
`stripe_user[block_kana]`Standard uniquement	La variation Kana du bloc d’adresse. Ce paramètre est uniquement pertinent pour le Japon. Vous devez préremplir `stripe_user[country]` avec JP et `stripe_user[zip]` avec un code postal japonais valide pour utiliser ce paramètre.
`stripe_user[block_kanji]`Standard uniquement	La variation Kanji du bloc d’adresse. Ce paramètre est uniquement pertinent pour le Japon. Vous devez préremplir `stripe_user[country]` avec JP et `stripe_user[zip]` avec un code postal japonais valide pour utiliser ce paramètre.
`stripe_user[building_kana]`Standard uniquement	La variation Kanji du bâtiment de l’adresse. Ce paramètre est uniquement pertinent pour le Japon. Vous devez préremplir `stripe_user[country]` avec JP et `stripe_user[zip]` avec un code postal japonais valide pour utiliser ce paramètre.
`stripe_user[building_kanji]`Standard uniquement	La variation Kana du bâtiment de l’adresse. Ce paramètre est uniquement pertinent pour le Japon. Vous devez préremplir `stripe_user[country]` avec JP et `stripe_user[zip]` avec un code postal japonais valide pour utiliser ce paramètre.

Réponse

Le navigateur de l’utilisateur est redirigé vers votre URI de redirection configuré ou vers la valeur que vous avez transmise dans le paramètre redirect_uri. Lorsque l’opération aboutit, vous recevez les paramètres de requête suivants :

Paramètre	Description
`code`	Un code d’autorisation que vous pouvez utiliser dans le prochain appel pour obtenir un token d’accès pour votre utilisateur. Il ne peut être utilisé qu’une fois et expire au bout de 5 minutes.
`scope`	read_write ou read_only, selon ce que vous avez transmis dans la requête GET initiale.
`state`	La valeur du paramètre `state` que vous avez fournie dans la requête GET initiale.

Réponse d’erreur

En cas d’erreur, le navigateur de l’utilisateur ne sera pas redirigé, sauf en cas de access_denied. Au lieu de cela, des erreurs seront renvoyées dans un dictionnaire JSON avec les champs suivants :

Paramètre	Description
`error`	Un code d’erreur unique par type d’erreur.
`error_description`	Une description de l’erreur lisible par un humain.
`state`	La valeur du paramètre `state` que vous avez fournie dans la requête GET initiale.

Codes d’erreur

Paramètre	Description
`access_denied`	Autorisation refusée pour l’utilisateur.
`invalid_scope`	Paramètre `scope` non valide fourni.
`invalid_redirect_uri`	Le paramètre `redirect_uri` fourni est une URL non valide ou n’est pas autorisé par les paramètres de votre application.
`invalid_request`	Paramètre `response_type` manquant.
`unsupported_response_type`	Paramètre `response_type` non pris en charge. Le seul `response_type` actuellement pris en charge est code.

Terminer la connexion et obtenir l’ID du compte

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

Les deux sont utilisés pour convertir un authorization_code en connexion au compte, et pour obtenir un nouveau token d’accès avec un refresh_token.

Requête

Effectuez cet appel avec votre clé API secrète en tant que paramètre POST client_secret :

Lorsque vous convertissez un code d’autorisation en token d’accès, vous devez utiliser une clé API qui corresponde au mode (production ou test) du code d’autorisation (ce qui dépend du mode d’utilisation du client_id utilisé : production ou développement).

Si vous utilisez un token d’actualisation pour demander un token d’accès, vous pouvez utiliser une clé API de production ou test pour obtenir un token d’accès de production ou test respectivement. Tout token d’accès existant avec le même périmètre et mode (production ou test) est révoqué.

Remarque

Pour OAuth v2, cet endpoint est idempotent. L’utilisation d’un code d’autorisation plus d’une fois révoque la connection au compte.

Paramètre	Description
`grant_type`	authorization_code lors de la conversion d’un code d’autorisation en token d’accès, ou refresh_token si utilisation d’un token d’actualisation pour obtenir un nouveau token d’accès.
`code` ou `refresh_token`	La valeur du `code` ou `refresh_token`, selon le `grant_type`.
`scope`Facultatif	Lors de la demande d’un nouveau token d’accès à partir d’un token d’actualisation, tout périmètre ayant un périmètre inférieur ou égal comme token d’actualisation. N’a aucune incidence lors d’une demande de token d’accès à partir d’un code d’autorisation. Est défini par défaut sur le périmètre du token d’actualisation.

Réponse

Paramètre	Description
`scope`	Le périmètre accordé au token d’accès, selon le périmètre du code d’autorisation et du paramètre `scope`.
`stripe_user_id`	L’ID unique du compte auquel vous avez accès, comme chaîne.
`livemode`	Indique si la plateforme peut effectuer des modifications au nom du compte connecté en mode production ou si ses actions sont limitées au mode test. Ce paramètre correspond à l’accès au mode production permettant d’autoriser la requête OAuth request.
`token_type`	Possède toujours la valeur bearer.
`access_token`	Deprecated Utilisez l’en-tête `Stripe-Account` avec la clé secrète de votre plateforme (qui permet d’effectuer des requêtes au nom de ce compte Stripe).
`stripe_publishable_key`	Deprecated Utilisez l’en-tête `Stripe-Account` avec la clé publique de votre plateforme (qui permet d’effectuer des requêtes au nom de ce compte Stripe).
`refresh_token`	Deprecated Peut être utilisé pour obtenir un nouveau token de niveau équivalent, de niveau inférieur ou d’un autre mode production (le cas échéant).

Réponse d’erreur

Paramètre	Description
`error`	Un code d’erreur unique par type d’erreur.
`error_description`	Une description de l’erreur lisible par un humain.

Codes d’erreur

Paramètre	Description
`invalid_request`	Aucun paramètre `code`, `refresh_token`, ou `grant_type` fourni (si requis).
`invalid_grant`	Un ensemble de choses peuvent entraîner cette erreur : Le `code` n’existe pas, a expiré, a été utilisé, ou ne vous appartient pas Le `refresh_token` n’existe pas, ou ne vous appartient pas Le mode de la clé API (test ou production) ne correspond pas au mode `code` ou `refresh_token`
`unsupported_grant_type`	Paramètre `grant_type` non pris en charge indiqué. Les seuls types pris en charge actuellement sont authorization_code et refresh_token.
`invalid_scope`	Paramètre `scope` non valide fourni.
`unsupported_response_type`	Paramètre `response_type` non pris en charge. Le seul `response_type` actuellement pris en charge est code.

Révoquer l’accès au compte

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

Utilisé pour révoquer l’accès à un compte.

Remarque

Vous pouvez uniquement révoquer l’accès d’un compte Standard à votre plateforme.

Requête

Effectuez cet appel avec votre clé API secrète comme en-tête d’autorisation.

Lorsque vous révoquez l’accès à un compte, vous devez utiliser une clé API correspondant au mode (test ou production) utilisé pour vous connecter au compte. Utilisez une clé API en mode production si la connexion a été créée avec un client_id de production, ou une clé API en mode test s’il s’agit d’un client_id de développement.

Paramètre	Description
`client_id`	Le `client_id` de l’application de laquelle vous souhaitez déconnecter le compte. Le compte doit être connecté à cette application.
`stripe_user_id`	Le compte duquel vous voulez vous déconnecter.

Réponse

Paramètre	Description
`stripe_user_id`	L’ID unique du compte pour lequel vous avez révoqué l’accès, sous forme de chaîne. Il s’agit du même ID que le `stripe_user_id` que vous avez transmis. S’il est renvoyé, la révocation est réussie.

Réponse d’erreur

Paramètre	Description
`error`	Un code d’erreur unique par type d’erreur.
`error_description`	Une description de l’erreur lisible par un humain.

Codes d’erreur

Paramètre	Description
`invalid_request`	Aucun paramètre `client_id` ou `stripe_user_id` fourni (si requis).
`invalid_client`	Un ensemble de choses peuvent entraîner cette erreur : Le `client_id` ne vous appartient pas Le `stripe_user_id` n’existe pas ou n’est pas connecté à votre application Le mode de la clé API (test ou production) ne correspond pas au mode `client_id`. `no_deauth_on_controlled_account` le compte ne peut pas être déconnecté, utilisez plutôt l’API rejection.