Utilisation de OAuth avec des comptes ExpressObsolète

Utilisez le flux de connexion OAuth pour permettre à un utilisateur Express de se connecter à votre plateforme.

Mise en garde

OAuth n’est pas disponible pour les nouvelles plateformes Connect. Pour les nouveaux comptes, utilisez plutôt l’API Accounts avec Express. Il n’est pas recommandé d’utiliser Express OAuth pour les extensions, car elles ne peuvent pas se connecter aux comptes Express existants. Si vous avez besoin d’accéder à OAuth pour les comptes Express, veuillez contacter le service Support.

Le flux de connexion OAuth

Un utilisateur se connecte à votre plateforme à l’aide du flux de connexion OAuth suivant :

Sur une page de votre site, vous fournissez un lien qui redirige votre client vers Stripe, indiquant ainsi le client_id de votre plateforme.
Sur le site Web de Stripe, l’utilisateur fournit les informations nécessaires pour se connecter à votre plateforme.
Stripe redirige l’utilisateur vers votre site, avec un code d’autorisation.
Votre site envoie alors une requête à l’endpoint de token OAuth pour finaliser la connexion et récupérer l’ID du compte de l’utilisateur.

Une fois que ces étapes sont terminées, vous pouvez effectuer des requêtes d’API pour l’utilisateur avec l’ID de son compte.

Étape 1 : vous fournissez le lien OAuth

Pour démarrer votre intégration, rendez-vous sur les paramètres de votre plateforme, puis :

Activez l’inscription des comptes Express avec OAuth dans les paramètres OAuth.
Copiez votre client_id, un identifiant unique de votre plateforme généré par Stripe.
Définissez votre redirect_uri, l’URL vers laquelle votre utilisateur est redirigé une fois connecté à son compte. Vous devez indiquer toutes les URL de redirection dans les paramètres de votre plateforme. Si vous n’intégrez pas le paramètre redirect_uri dans votre requête, Stripe utilise par défaut la première adresse configurée dans les paramètres de votre plateforme.

Stripe propose également un client_id de développement pour faciliter les tests.

Une fois ces paramètres définis, vous pouvez créer le lien OAuth. Nous vous recommandons d’afficher un bouton Connexion dont le rôle sera de diriger les utilisateurs vers l’endpoint OAuth d’Express :

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

Ajoutez le paramètre state avec un token unique comme valeur, afin d’éviter toute attaque CSRF. Stripe inclut cette valeur state dans l’URL de redirection qui redirige l’utilisateur vers votre site. Confirmez ensuite que le paramètre state n’a pas été modifié.

Voici comment l’URL en exemple peut s’afficher, en cliquant sur notre bouton Connexion à Stripe :

Connexion à

Personnalisation d’Express avec les paramètres OAuth

Vous pouvez modifier le comportement du flux d’inscription Express en intégrant des paramètres d’URL supplémentaires dans votre lien OAuth. La liste complète des paramètres disponibles est accessible dans la documentation relative à OAuth.

Comptes de particuliers ou d’entreprises

Vous pouvez spécifier si Stripe présente un formulaire d’inscription Express pour les particuliers ou les entreprises en définissant le paramètre stripe_user[business_type] soit sur individual, soit sur company.

Stripe collecte les informations appropriées pour chaque type de compte. Par exemple, pour inscrire une entreprise :

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

Préremplir les champs du formulaire

Vous pouvez préremplir certains des champs du formulaire sur l’application Stripe de l’utilisateur en incluant les paramètres d’URL adaptés dans votre lien OAuth.

Cet exemple préremplit l’adresse e-mail de l’utilisateur avec stripe_user[email] :

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

Spécifier les fonctionnalités pour un compte

Vous pouvez modifier les fonctionnalités pour les nouveaux comptes connectés dans les paramètres du Dashboard pour Express. Cependant, si vous souhaitez demander des fonctionnalités différentes pour chacun de vos comptes connectés, vous pouvez inclure le paramètre suggested_capabilities[] dans votre lien OAuth et remplacer les paramètres du Dashboard sur la page de configuration d’Express.

Un exemple avec la fonctionnalité 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 ajoute la fonctionnalité suggérée à ce compte Express, sauf si l’une des conditions suivantes est remplie :

Si l’utilisateur est dans un pays qui ne prend pas en charge les transfers, Stripe essaye de déterminer le compte comme card_payments.
Si le compte de l’utilisateur ne prend pas en charge les transfers ou les card_payments, Stripe indique que le compte n’a pas de fonctionnalités.

Vous pouvez vérifier que Stripe a ajouté la fonctionnalité suggérée en utilisant le paramètre assert_capabilities[]. Cette étape est facultative.

Étape 2 : l’utilisateur crée son compte

Lorsque l’utilisateur clique sur le lien de votre site, il est redirigé vers le site Web de Stripe. Il lui est alors demandé de fournir ses coordonnées et les informations permettant d’effectuer des virements.

Site Web de Stripe permettant à l'utilisateur de fournir ses coordonnées et ses informations de virement

Pour tester le processus d’inscription, vous pouvez fournir (000) 000-0000 comme numéro de téléphone. Plutôt que de vous envoyer un message par SMS ou e-mail, Stripe vous laisse terminer la vérification avec le code 000-000.

Express affiche votre marque dans le flux d’inscription et le Dashboard d’Express. Vous pouvez fournir le nom, le logo et, en option, la couleur de marque de votre plateforme dans la section paramètres de Connect du Dashboard de Stripe.

Étape 3 : Stripe redirige l’utilisateur vers votre site

Une fois que l’utilisateur a complété le processus d’inscription, Stripe le redirige vers votre site à l’aide de l’URL définie en tant que redirect_uri de votre plateforme.

Pour que la connexion fonctionne, l’URL de redirection doit inclure les valeurs suivantes :

La valeur state, le cas échéant.
Un code d’autorisation. Le code d’autorisation est un code éphémère et ne peut être utilisé qu’une seule fois, dans la requête POST décrite à l’étape suivante.

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

Étape 4 : vous terminez la connexion du compte Express

Intégrez le code d’autorisation fourni dans une requête POST à l’endpoint de token de Stripe pour finaliser la connexion et récupérer l’ID de compte de l’utilisateur :

Stripe renvoie une réponse incluant l’ID de compte (stripe_user_id) de l’utilisateur :

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

Ou, si un problème se produit, Stripe renvoie un message d’erreur détaillé :

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

L’utilisateur est désormais connecté à votre plateforme. Le stripe_user_id est l’ID du compte Stripe pour le nouveau compte. Conservez cette valeur dans votre base de données et utilisez-la pour l’authentification comme compte connecté en la passant dans les requêtes dans l’en-tête de Stripe-Account.

Remarque

Conservez le stripe_user_id, qui est l’ID du compte. Les plateformes nécessitent cette valeur (commençant par acct_) pour transférer les fonds, créer des paiements et effectuer des requêtes pour le compte des utilisateurs.

Vérifier la fonctionnalité du compte

Si vous fournissez le paramètre suggested_capabilities[], vous pouvez ajouter le paramètre assert_capabilities[] pour vérifier que le compte connecté ait désormais les fonctionnalités suggérées. Par exemple, vous pouvez le vérifier si vous êtes préoccupé par la sécurité de l’URL. Cette étape est néanmoins facultative. Stripe gère tout échec d’application d’une fonctionnalité sans vous importuner.

Une réponse indiquant une réussite ressemble à ceci :

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

Si la valeur capabilities[] spécifiée ne correspond pas, la réponse d’erreur ressemble à ceci :

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

La raison la plus courante d’un échec d’une requête est que la fonctionnalité spécifiée n’est pas disponible dans le pays de votre utilisateur. La modification de l’URL par un contrevenant est moins probable.

Webhooks

Après la création d’un compte, toutes les notifications concernant les changements affectant le compte sont envoyées à vos webhooks comme événements account.updated. Indiquez l’URL du webhook Connect dans vos paramètres de compte. Ces événements vous permettent de suivre l’état de l’inscription et de la vérification des comptes connectés, ils peuvent être utilisés pour fournir une assistance à l’utilisateur et afficher des avis dans l’interface utilisateur de votre plateforme. Vous pouvez aussi laisser Stripe guider vos utilisateurs à travers les étapes du processus d’inscription et de vérification et gérer toute éventuelle difficulté.

Si vous avez créé un compte dans un environnement de test à l’aide d’une clé API de test ou un client_id, Stripe n’envoie pas d’e-mails pendant que vous développez votre intégration Stripe (en revanche, nous envoyons des e-mails en mode production.)