Premiers pas avec les composants intégrés Connect
Utilisez les composants Connect intégrés pour ajouter les fonctionnalités du Dashboard des comptes connectés à votre site Web. Grâce à ces bibliothèques et leurs API, vos utilisateurs pourront accéder aux produits Stripe directement depuis votre Dashboard.
Pour une version immersive de ce guide, consultez le guide de démarrage rapide sur l’intégration des composants intégrés Connect. Vous pouvez également télécharger un exemple d’intégration depuis ce guide. Pour personnaliser l’apparence des composants intégrés Connect, utilisez les options appearance
lorsque vous initialisez StripeConnectInstance
. Consultez la liste complète des paramètres d’apparence dans la section dédiée.
Initialiser Connect.jsCôté clientCôté serveur
Stripe utilise une AccountSession qui permet d’indiquer votre intention de déléguer l’accès à l’API à votre compte connecté.
L’API AccountSessions renvoie une clé secrète du client qui permet à un composant intégré dans le client Web d’accéder aux ressources d’un compte connecté comme si vous effectuiez les appels à l’API à sa place.
Créer une AccountSession Server
Par le biais d’un formulaire d’une page, votre client émet une demande pour obtenir la session de compte de votre serveur. Vous pouvez créer un nouveau endpoint sur votre serveur qui renvoie la clé secrète du client au navigateur :
Configurer Connect.js Client
Charger et initialiser Connect.js Client
Appelez loadConnectAndInitialize
avec votre clé publique et une fonction qui récupère une clé secrète en appelant le nouveau point de terminaison que vous avez créé sur votre serveur. Utilisez la StripeConnectInstance
renvoyé pour créer des composants intégrés. Après avoir initialisé Connect.js, vous pouvez monter des composants sur le DOM ou les démonter à tout moment. Cela inclut tous les éléments affichés dans les portails React ou Vue.
Consulter la liste complète des composants intégrés pris en charge→
Configurer Connect.jsCôté client
La méthode loadConnectAndInitialize
côté client nécessite plusieurs options pour configurer Connect.js.
Option | Description | |
---|---|---|
publishableKey | La clé publiable de votre intégration. | obligatoire |
fetchClientSecret | Fonction qui récupère la clé secrète du client renvoyée par /v1/account_sessions . Cela indique à StripeConnectInstance à quel compte déléguer l’accès. Cette fonction est également utilisée pour récupérer une fonction secrète du client afin d’actualiser la session lorsqu’elle expire. | obligatoire |
appearance | Objet permettant de personnaliser l’apparence des composants intégrés Connect. | facultatif |
locale | Paramètre permettant de spécifier la langue utilisée par les composants intégrés Connect. Par défaut, la langue du navigateur est utilisée. Si la langue transmise n’est pas directement prise en charge, un paramètre raisonnablement similaire est utilisé (par exemple, fr-fr peut être utilisé à la place de fr-be ). | facultatif |
fonts | Un tableau de polices personnalisées pouvant être utilisées par tout composant intégré créé à partir d’une StripeConnectInstance . Les polices peuvent être spécifiées en tant qu’objets CssFontSource ou CustomFontSource. | facultatif |
Personnaliser l’apparence des composants intégrés Connect
Nous vous proposons un ensemble d’options de personnalisation des composants Connect intégrés. Vous pouvez personnaliser l’apparence des boutons, des icônes et d’autres éléments dans notre système de design.
Vous pouvez configurer ces options à l’initialisation de StripeConnectInstance
en transmettant des valeurs à l’objet appearance
. Vous pouvez uniquement utiliser les options Connect.js pour modifier l’apparence des composants intégrés Connect. La famille de polices et la couleur d’arrière-plan des composants intégrés Connect peuvent être remplacées à l’aide de sélecteurs CSS, mais Stripe ne prend pas en charge le remplacement d’autres styles.
const fetchClientSecret = async () => { const response = await fetch('/account_session'); const {client_secret: clientSecret} = await response.json(); return clientSecret; } const stripeConnectInstance = loadConnectAndInitialize({ publishableKey:
, fetchClientSecret: fetchClientSecret, fonts: [ { cssSrc: "https://myfonts.example.com/mycssfile.css", }, { src: `url(https://my-domain.com/assets/my-font-2.woff)`, family: 'My Font' } ], appearance: { // See all possible variables below overlays: "dialog", variables: { fontFamily: 'My Font', colorPrimary: "#FF0000", }, }, });"pk_test_TYooMQauvdEDq54NiTphI7jx"
L’objet fonts
L’objet fonts
de stripeConnect.initialize
accepte un tableau d’objets CssFontSource ou CustomFontSource.
Si votre page utilise des polices personnalisées (c’est-à-dire des fichiers .woff
ou .tff
), vous devez spécifier ces fichiers lors de l’initialisation des composants intégrés Connect. Cela leur permet d’afficher correctement ces polices. Vous pouvez les spécifier comme suit :
CssFontSource
Utilisez cet objet pour transmettre une URL de feuille de style qui définit vos polices personnalisées lors de la création d’une instance StripeConnectInstance
. Avec un objet CssFontSource, votre configuration CSP doit permettre de récupérer les domaines associés aux URL de fichiers CSS spécifiées comme CssFontSource.
Nom | Type | Exemple de valeur |
cssSrc | chaîne required | https://fonts.googleapis.com/css?family=Open+Sans |
Une URL relative ou absolue pointant vers un fichier CSS avec des définitions de @font-face. Lorsque vous utilisez une politique de sécurité du contenu (CSP), des directives supplémentaires peuvent s’appliquer. |
CustomFontSource
Utilisez cet objet pour transmettre des polices personnalisées lors de la création d’un StripeConnectInstance
.
Nom | Type | Exemple de valeur |
family | chaîne required | Avenir |
Le nom à donner à la police. | ||
src | chaîne required | url(https://my-domain.com/assets/avenir.woff) |
Une valeur src valide pointant vers votre fichier de police personnalisé. Il s’agit généralement (mais pas toujours) d’un lien vers un fichier .woff , .otf ou .svg . | ||
display | chaîne optional | auto |
Une valeur font-display valide. | ||
style | chaîne optional | normal |
L’une des valeurs suivantes : normal , italic ou oblique . | ||
unicodeRange | chaîne optional | U+0-7F |
Une valeur unicode-range valide. | ||
weight | chaîne optional | 400 |
Un font-weight valide. Il s’agit d’une chaîne de caractères et non d’un nombre. |
L’objet appearance
L’objet appearance
dans loadConnectAndInitialize
accepte les propriétés facultatives suivantes :
Nom | Type | Exemple de valeur |
overlays | ‘dialog’ (par défaut) | ‘drawer’ | dialog |
Le type de superposition utilisé dans l’ensemble du système de conception Connect.js. Définissez ce paramètre sur Dialog ou Drawer. | ||
variables | objet | {colorPrimary: "#0074D4"} |
Consultez la liste complète des variables d’apparence. |
Mettre à jour les composants intégrés Connect après l’initialisation
La méthode update
prend en charge la mise à jour des composants intégrés Connect après l’initialisation. Cela permet de changer les options d’apparence au moment de l’exécution (sans actualiser la page). Pour ce faire, utilisez l’objet stripeConnectInstance
que vous avez précédemment créé à l’aide de initialize
, puis faites appel à la méthode update
:
stripeConnectInstance.update({ appearance: { variables: { colorPrimary: "#FF0000", }, }, locale: 'en-US', });
Note
Vous ne pouvez pas mettre à jour toutes les options (p. ex., fonts
). Les options prises en charge pour cette méthode sont un sous-ensemble des options proposées dans initialize
. Cela permet de mettre à jour les paramètres appearance
et locale
.
Largeur et hauteur
Les composants intégrés Connect se comportent comme des éléments HTML block
standard. Par défaut, ils prennent 100 % de la largeur width
de leur élément HTML parent et croissent en hauteur en fonction du contenu affiché à l’intérieur. Vous pouvez contrôler la largeur width
des composants intégrés Connect en spécifiant la largeur width
du parent HTML. Vous ne pouvez pas contrôler directement la hauteur height
, car elle dépend du contenu affiché. Cependant, vous pouvez limiter la hauteur avec maxHeight
et overflow: scroll
, comme avec les autres éléments HTML block
.
Authentification
Nous proposons un ensemble d’API permettant de gérer les sessions de compte et les identifiants des utilisateurs dans les composants intégrés Connect.
Actualiser la clé secrète du client
Pour les sessions de longue durée, la session issue de la clé secrète du client initialement fournie peut expirer. À son expiration, nous utilisons automatiquement fetchClientSecret
pour récupérer une nouvelle clé secrète du client et actualiser la session. Vous n’avez pas besoin de transmettre de paramètres supplémentaires.
import { loadConnectAndInitialize } from "@stripe/connect-js"; // Example method to retrieve the client secret from your server const fetchClientSecret = async () => { const response = await fetch('/account_session'); const {client_secret: clientSecret} = await response.json(); return clientSecret; } const stripeConnectInstance = loadConnectAndInitialize({ publishableKey: "{{PUBLISHABLE_KEY}}", fetchClientSecret: fetchClientSecret, });
Se déconnecter
Nous vous recommandons d’appeler logout
sur stripeConnectInstance
pour supprimer l’objet Account Session associé une fois qu’un utilisateur se déconnecte de votre application. Cette action désactive tous les composants intégrés Connect qui sont liés à cette stripeConnectInstance
.
// Call this when your user logs out stripeConnectInstance.logout();
Exigences relatives aux en-têtes CSP et HTTP
Si votre site Web déploie une Politique de sécurité du contenu, vous devez la mettre à jour en ajoutant les règles suivantes :
frame-src
https://connect-js.stripe.com
https://js.stripe.com
img-src
https://*.stripe.com
script-src
https://connect-js.stripe.com
https://js.stripe.com
style-src
sha256-0hAheEzaMe6uXIKV4EehS9pu1am1lj/KnnzrOYqckXk=
(SHA d’élément de style vide)
Si vous utilisez un fichier CSS pour charger les polices Web à utiliser avec des composants Connect intégrés, son URL doit être autorisée par votre politique de sécurité du contenu connect-src.
La définition de certains en-têtes de réponse HTTP active toutes les fonctionnalités des composants intégrés Connect :
Cross-Origin-Opener-Policy
,unsafe-none
. Remarque : il s’agit de la valeur par défaut de l’en-tête, son paramétrage n’est donc pas possible.
Navigateurs pris en charge
Nous prenons en charge les mêmes navigateurs que ceux actuellement pris en charge par le Dashboard Stripe :
- Les 20 dernières versions majeures de Chrome et Firefox
- Les deux dernières versions majeures de Safari et Edge
- Les deux dernières versions majeures de Safari mobile sur iOS
Les composants intégrés Connect ne sont pas pris en charge dans les vues Web. Ils sont uniquement pris en charge par les navigateurs individuels.
Langues prises en charge
Nous avons localisé les composants intégrés Connect dans les langues suivantes :
Langue | Code de langue |
---|---|
Bulgare (Bulgarie) | bg-BG |
Chinois (simplifié) | zh-Hans |
Chinois (traditionnel - Hong Kong) | zh-Hant-HK |
Chinois (traditionnel - Taïwan) | zh-Hant-TW |
Croate (Croatie) | hr-HR |
Tchèque (Tchéquie) | cs-CZ |
Danois (Danemark) | da-DK |
Néerlandais (Pays-Bas) | nl-NL |
Anglais (Australie) | en-AU |
Anglais (Inde) | en-IN |
Anglais (Irlande) | en-IE |
Anglais (Nouvelle-Zélande) | en-NZ |
Anglais (Singapour) | en-SG |
Anglais (Royaume-Uni) | en-GB |
Anglais (États-Unis) | en-US |
Estonien (Estonie) | et-EE |
Philippin (Philippines) | fil-PH |
Finnois (Finlande) | fi-FI |
Français (Canada) | fr-CA |
Français (France) | fr-FR |
Allemand (Allemagne) | de-DE |
Grec (Grèce) | el-GR |
Hongrois (Hongrie) | hu-HU |
Indonésien (Indonésie) | id-ID |
Italien (Italie) | it-IT |
Japonais (Japon) | ja-JP |
Coréen (Corée du Sud) | ko-KR |
Letton (Lettonie) | lv-LV |
Lituanien (Lituanie) | lt-LT |
Malais (Malaisie) | ms-MY |
Maltais (Malte) | mt-MT |
Norvégien Bokmål (Norvège) | nb-NO |
Polonais (Pologne) | pl-PL |
Portugais (Brésil) | pt-BR |
Portugais (Portugal) | pt-PT |
Roumain (Roumanie) | ro-RO |
Slovaque (Slovaquie) | sk-SK |
Slovène (Slovénie) | sl-SI |
Espagnol (Argentine) | es-AR |
Espagnol (Brésil) | es-BR |
Espagnol (Amérique latine) | es-419 |
Espagnol (Mexique) | es-MX |
Espagnol (Espagne) | es-ES |
Suédois (Suède) | sv-SE |
Thaï (Thaïlande) | th-TH |
Turc (Turquie) | tr-TR |
Vietnamien (Vietnam) | vi-VN |
Intégration sans paquet NPM front-end
Nous vous recommandons d’effectuer l’intégration avec nos wrappers de composants React ou Javascript, qui simplifient le chargement des composants intégrés Connect et fournissent des définitions TypeScript pour nos interfaces prises en charge. Si votre système ne prend pas actuellement en charge les dépendances à des paquets, vous pouvez procéder à l’intégration sans ces paquets.
Ajoutez manuellement la balise de script Connect.js au <head>
de chaque page de votre site.
<!-- Somewhere in your site's <head> --> <script src="https://connect-js.stripe.com/v1.0/connect.js" async></script>
Utilisation de Connect.js without NPM
Une fois que Connect.js a terminé son chargement, il initialise la variable globale de fenêtre StripeConnect
et appelle StripeConnect.onLoad
si vous l’avez définie. Vous pouvez initialiser Connect.js en toute sécurité en mettant en place une fonction onload
et en appelant StripeConnect.init
avec les mêmes options Connect.js que loadConnectAndInitialize
.
window.StripeConnect = window.StripeConnect || {}; StripeConnect.onLoad = () => { const stripeConnectInstance = StripeConnect.init({ // This is a placeholder - it should be replaced with your publishable API key. // Sign in to see your own test API key embedded in code samples. // Don’t submit any personally identifiable information in requests made with this key. publishableKey:
, fetchClientSecret: fetchClientSecret, }); const payments = stripeConnectInstance.create('payments'); document.body.appendChild(payments); };"pk_test_TYooMQauvdEDq54NiTphI7jx"
Authentification de l’utilisateur dans les composants intégrés de Connect
Les composants intégrés de Connect ne requièrent généralement pas d’authentification de l’utilisateur : Ils offrent directement les fonctionnalités pour lesquelles ils sont configurés. Dans certains cas, les composants intégrés de Connect nécessitent que l’utilisateur s’identifie avec son compte Stripe pour exécuter les fonctionnalités requises par ce composant (par exemple, saisir des informations dans le compte de l’entité juridique dans le cas du composant d’inscription des utilisateurs).
Lors de l’authentification, une boîte de dialogue Stripe s’ouvre. Une fois que l’utilisateur s’est authentifié dans cette boîte, celle-ci se ferme et il peut poursuivre ses activités.
Les composants d’inscription des utilisateurs et de gestion des comptes nécessitent une authentification au démarrage. D’autres composants peuvent nécessiter l’authentification de l’utilisateur dans le composant après l’affichage initial. Dans ces composants et dans ces cas, l’authentification est requise pour tous les types de comptes connectés, à l’exception des comptes Custom pour lesquels la plateforme n’a pas configuré la collecte de comptes externes dans le Dashboard Stripe.