Premiers pas avec les composants intégrés Connect

Comment intégrer les fonctionnalités du Dashboard à votre site Web.

Utilisez les composants intégrés Connect pour ajouter des fonctionnalités de Dashboard de compte connecté à votre site Web. Ces bibliothèques et leur API associée vous permettent d’offrir à vos utilisateurs la possibilité d’accéder aux produits Stripe directement depuis votre Dashboard et vos applications mobiles.

Web

iOS

Android

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.js
Côté client
Côté serveur

Stripe utilise une AccountSession pour exprimer votre intention de déléguer API accès à votre compte connecté.

L’API AccountSessions renvoie une clé secrète du client qui permet à un composant intégré d’accéder aux ressources d’un compte connecté comme si vous faisiez des appels à l’API pour ces derniers.

Créer une AccountSession Serveur

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 :

API Create Account Session

L’API Create Account Session détermine l’accès aux composants et aux fonctionnalités des composants intégrés Connect. Stripe applique ces paramètres à tous les composants correspondant à la session du compte. Si votre site prend en charge plusieurs rôles d’utilisateur, vérifiez que les composants et fonctionnalités activés pour cette session de compte correspondent au rôle de l’utilisateur actuel. Par exemple, vous pouvez activer la gestion des remboursements uniquement pour les administrateurs de votre site, mais pas pour les autres utilisateurs. Pour vérifier que les accès aux rôles d’utilisateur sont appliqués, vous devez mapper le rôle d’utilisateur de votre site aux composants de session de compte.

Configurer Connect.js Client

Nous recommandons de configurer Connect.js avec npm comme indiqué dans l’exemple suivant, mais c’est également possible sans npm.

Installez le paquet NPM pour utiliser Connect.js en tant que module.

Command Line
npm install --save @stripe/connect-js

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.

Pour créer un composant, appelez create sur la StripeConnectInstance que vous avez créée ci-dessus, puis passez le nom du composant. Cela renvoie un custom element que Connect.js enregistre et utilise pour connecter automatiquement votre DOM à Stripe. Vous pouvez alors append cet élément à votre DOM.

Appelez create avec payments, puis ajoutez le résultat à votre DOM pour afficher une interface utilisateur de paiement.

Voir la liste complète des composants embarqués pris en charge →

Configure Connect.js
Côté client

La méthode loadConnectAndInitialize sur le client prend plusieurs options différentes pour configurer Connect.js.

Option	Description
`publishableKey`	La clé publiable de votre intégration.	obligatoire
`fetchClientSecret`	La 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 client afin d’actualiser la session à son expiration. `fetchClientSecret` doit toujours créer une nouvelle session de compte et renvoyer un nouveau `client_secret`.	obligatoire
`appearance`	Objet permettant de personnaliser l’apparence des composants Connect intégrés.	Facultatif
`locale`	Paramètre permettant de spécifier les paramètres locale utilisés par les composants Connect intégrés. Par défaut, ce paramètre est défini sur la langue du navigateur. Si les paramètres régionaux spécifiés ne sont pas directement pris en charge, une alternative raisonnable est utilisée (par exemple, `fr-be` peut se rabattre sur `fr-fr`). Reportez-vous à la section localisation pour obtenir la liste des paramètres régionaux pris en charge.	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

La boîte à outils de composants intégrés d’interface utilisateur Figma contient tous les composants, les modèles courants et un exemple d’application. Vous pouvez l’utiliser pour visualiser et concevoir des interfaces utilisateur intégrées sur votre site Web.

Nous proposons un ensemble d’options permettant de personnaliser l’apparence des composants intégrés Connect. Ces personnalisations affectent les boutons, les icônes et d’autres accents de notre système de conception.

Fenêtres contextuelles nécessaires

Certains comportements dans les composants intégrés, tels que l’authentification de l’utilisateur, doivent être présentés dans une fenêtre contextuelle. Vous ne pouvez pas personnaliser le composant intégré pour éliminer ces fenêtres contextuelles.

Vous pouvez définir ces options lors de l’initialisation de StripeConnectInstance en transmettant une apparence à l’objet appearance. Vous pouvez uniquement utiliser les options Connect.js pour modifier les styles dans les composants Connect intégrés. La famille de polices et la couleur d’arrière-plan des composants intégrés Connect sont héritées du conteneur HTML parent. Vous devez définir explicitement toutes les autres options.

index.js
const stripeConnectInstance = loadConnectAndInitialize({
  publishableKey: "pk_test_TYooMQauvdEDq54NiTphI7jx"
,
  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",
    },
  },
});

Reportez-vous à la liste complète des variables d’apparence.

L’objet fonts

L’objet fonts dans stripeConnect.initialize prend un tableau d’objets CssFontSource ou CustomFontSource.

Si vous utilisez des polices personnalisées sur votre page (par exemple, des fichiers .woff ou .tff), vous devez spécifier les fichiers de polices lors de l’initialisation des composants intégrés Connect. Cela permet aux composants intégrés Connect d’afficher correctement les polices. Vous pouvez spécifier les fichiers comme suit :

CssFontSource

Utilisez cet objet pour transmettre l’URL d’une feuille de style qui définit vos polices personnalisées lors de la création d’une StripeConnectInstance. Avec un objet CssFontSource, votre configuration CSP doit permettre d’extraire les domaines associés aux URL des fichiers CSS spécifiés en tant que 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. Le fichier doit être hébergé sur sur un serveur https. Si vous utilisez une politique de sécurité du contenu, des directives supplémentaires peuvent s’appliquer au fichier.

CustomFontSource

Utilisez cet objet pour transmettre des polices personnalisées lors de la création d’une StripeConnectInstance.

Nom	Type	Exemple de valeur
`family`	chaîne `required`	`Avenir`
Le nom à attribuer à la police.
`src`	chaîne `required`	`url(https://my-domain.com/assets/avenir.woff)`
Une valeur src valide pointant vers votre fichier de polices personnalisées. Il s’agit généralement (mais pas toujours) d’un lien vers un fichier `.woff`, `.otf` ou `.svg`. Le fichier doit être hébergé sur sur un serveur https.
`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`
Valeur valide unicode-range.
`weight`	chaîne `optional`	`400`
Un font-weight valide. Il s’agit d’une chaîne de caractères et non d’un nombre.

Mise à jour des composants intégrés de Connect après l’initialisation

La méthode update prend en charge la mise à jour des composants Connect Embedded après l’initialisation. Vous pouvez l’utiliser pour changer d’option d’apparence au moment de l’exécution (sans actualiser la page). Pour ce faire, utilisez le même objet stripeConnectInstance que vous avez créé avec initialize et appelez la méthode update sur celui-ci :

index.js
stripeConnectInstance.update({
  appearance: {
    variables: {
      colorPrimary: "#FF0000",
    },
  },
  locale: 'en-US',
});

Remarque

Toutes les options (par exemple, fonts) ne peuvent pas être mises à jour. Les options prises en charge pour cette méthode sont un sous-ensemble des options proposées dans initialize. Les modifications de appearance et locale sont prises en charge.

Largeur et hauteur

Les composants intégrés Connect se comportent comme des éléments HTML block ordinaires. Par défaut, ils prennent 100 % de la valeur width de leur élément HTML parent, et grandissent en hauteur en fonction du contenu rendu à l’intérieur. Vous pouvez contrôler la valeur width des composants Connect Embedded en spécifiant la valeur width du parent HTML. Vous ne pouvez pas contrôler directement le paramètre height, car il dépend du contenu rendu. Cependant, vous pouvez limiter la hauteur avec maxHeight et overflow: scroll, de la même manière que vous pouvez le faire avec d’autres éléments HTML block.

Authentification

Nous proposons un ensemble d’API pour gérer les sessions de compte et les informations d’identification des utilisateurs dans les composants Connect intégrés.

Actualiser la clé secrète du client

Sur les sessions de longue durée, la session du secret client peut expirer. Lorsqu’il expire, nous utilisons automatiquement fetchClientSecret pour récupérer une nouvelle clé secrète client et actualiser la session. Vous n’avez pas besoin de transmettre de paramètres supplémentaires.

index.js
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', { method: "POST" });
  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 détruire l’objet de session de compte associé une fois qu’un utilisateur se déconnecte de l’application. Cela désactive tous les composants Connect Embedded qui sont liés à cette stripeConnectInstance.

index.js
// Call this when your user logs out
stripeConnectInstance.logout();

Exigences relatives aux CSP et aux en-têtes HTTP

Si votre site Web met en œuvre 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.

Définir certains en-têtes de réponse HTTP permet d’activer toutes les fonctionnalités des composants intégrés Connect :

Cross-Origin-Opener-Policy, unsafe-none. unsafe-none est la valeur par défaut de l’en-tête. Vous pouvez ne pas le définir. D’autres valeurs, comme same-origin, interrompent l’authentification de l’utilisateur dans les composants intégrés Connect.

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 Connect Embedded ne sont pris en charge que dans les navigateurs Web et ne peuvent pas être utilisés dans les vues Web intégrées dans les applications mobiles ou de bureau.

Localisation

Lors de l’initialisation de Connect.js, vous pouvez transmettre un paramètre locale. Pour faire correspondre les paramètres régionaux d’un composant intégré à ceux de votre site Web, transmettez le paramètre locale avec les paramètres régionaux de l’interface utilisateur affichée par votre site Web.

La valeur par défaut du paramètre locale est déterminée par les paramètres régionaux configurés du navigateur. Si les paramètres régionaux spécifiés ne sont pas directement pris en charge, une alternative raisonnable est utilisée (par exemple, fr-be peut se rabattre sur fr-fr).

Les composants Connect Embedded prennent en charge les langues ou régions suivantes :

Langue	Code de paramètres régionaux
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 (Viêt Nam)	`vi-VN`

Traiter les erreurs de chargement

Si un composant ne parvient pas à se charger, vous pouvez réagir en fournissant un gestionnaire d’erreur de chargement à tout composant intégré. Selon la cause de l’échec, le gestionnaire d’erreur de chargement peut être appelé plusieurs fois. Toute logique déclenchée par un gestionnaire d’erreur de chargement doit être idempotente.

Moyen de paiement	Description	Variables
`setOnLoadError`	Le composant exécute cette fonction de rappel lorsqu’un échec de chargement se produit.	`loadError.error` : voir l’objet d’erreur de chargement `loadError.elementTagName` : nom de la balise HTML utilisée pour afficher le composant dans le navigateur

L’objet `error` de chargement

Chaque fois qu’il y a un échec de chargement, un objet error est transmis au gestionnaire d’erreur de chargement avec les propriétés suivantes.

Nom	Type	Exemple de valeur
`type`	Voir Types d’échec de chargement	`authentication_error`
Le type d’erreur
`message`	chaîne \| non défini	`Failed to fetch account session`
Description supplémentaire de l’erreur

Types d’échec de chargement

Lorsqu’un composant ne parvient pas à se charger, nous détectons le type de défaillance et l’associons à l’un des types ci-dessous. Si le type d’erreur de chargement ne peut pas être déterminé, il est marqué comme un ‘api_error.

Type	Description
`api_connection_error`	Échec de la connexion à l’API Stripe
`authentication_error`	Échec du flux d’authentification dans les composants intégrés Connect
`account_session_create_error`	Échec de la création de la session de compte
`invalid_request_error`	La requête a échoué avec un code d’état 4xx, généralement dû à des problèmes de configuration de la plateforme
`rate_limit_error`	La requête a échoué en raison de la détection d’un taux de requêtes anormal
`api_error`	Erreurs d’API couvrant tout autre type de problème, par exemple un problème temporaire au niveau des serveurs de Stripe

Détecter l’affichage de composants intégrés

Après la création d’un composant, aucune interface utilisateur n’est présentée aux utilisateurs tant que le javascript du composant n’est pas chargé et analysé dans le navigateur. De ce fait, les composants peuvent apparaître comme une fenêtre contextuelle une fois leur chargement terminé. Pour éviter cette situation, affichez votre propre interface utilisateur de chargement avant la création du composant et masquez l’interface utilisateur après l’affichage du composant. Tous les composants intégrés peuvent accepter une fonction de rappel qui est appelée immédiatement lorsqu’une interface utilisateur (y compris les indicateurs de chargement) est présentée à l’utilisateur.

Moyen de paiement	Description	Variables
`setOnLoaderStart`	Le composant exécute cette fonction de rappel lorsqu’une interface utilisateur (y compris les indicateurs de chargement) est présentée à l’utilisateur.	`event.elementTagName` : nom de la balise HTML utilisée pour afficher le composant dans le navigateur

Utiliser Connect.js sans npm

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>

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 configurant une fonction onload et en appelant StripeConnect.init avec les mêmes options Connect.js que loadConnectAndInitialize. Vous pouvez utiliser l’instance Connect renvoyée par init de la même manière que vous utilisez l’instance renvoyée par loadConnectAndInitialize pour créer des composants intégrés dans une intégration HTML + JS.

index.js
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: "pk_test_TYooMQauvdEDq54NiTphI7jx"
,
      fetchClientSecret: fetchClientSecret,
    });

  const payments = stripeConnectInstance.create('payments');
  document.body.appendChild(payments);
};

Authentification de l’utilisateur dans les composants intégrés de Connect

Les composants intégrés Connect ne requièrent généralement pas l’authentification de l’utilisateur. Dans certains cas, les composants intégrés Connect nécessitent que le compte connecté s’identifie avec son compte Stripe avant d’accéder au composant afin de fournir les fonctionnalités requises (par exemple, saisir des informations sur le compte de l’entité juridique dans le cas du composant d’inscription des utilisateurs). D’autres composants peuvent nécessiter une authentification au sein du composant après l’affichage initial.

L’authentification est obligatoire pour les comptes connectés pour lesquels Stripe est responsable de la collecte des informations mises à jour lorsque les exigences évoluent. Pour les comptes connectés pour lesquels vous êtes responsable de la collecte des informations mises à jour lorsque les exigences arrivent à échéance ou évoluent, tels que les comptes Custom, l’authentification de Stripe est contrôlée par la fonctionnalité de session de compte disable_stripe_user_authentication. Nous vous recommandons de mettre en œuvre l’authentification à deux facteurs ou des mesures de sécurité équivalentes à titre de bonne pratique. Pour les configurations de compte qui prennent en charge cette fonctionnalité, comme les comptes Custom, vous assumez la responsabilité des comptes connectés s’ils ne sont pas en mesure de rembourser les soldes négatifs.

Composants nécessitant une authentification

Lors de l’authentification, une boîte de dialogue Stripe s’ouvre. Le compte connecté doit s’identifier avant de pouvoir continuer ses activités.

Dans certains cas, les comptes connectés doivent s’authentifier pour utiliser les composants suivants :

Bonnes pratiques en matière de performance

Pour vous assurer que le temps de chargement des composants intégrés Connect est aussi faible que possible, suivez ces recommandations :

Appelez loadConnectAndInitialize le plus tôt possible dans votre flux.
Créez une instance de connexion unique : créez une instance de connexion unique en n’appelant loadConnectAndInitialize qu’une seule fois par session. Réutilisez ensuite cette instance pour créer et gérer plusieurs composants. Une erreur courante consiste à créer une instance de connexion par composant ou plusieurs instances de connexion par session. Cela entraîne une consommation de ressources et des requêtes API supplémentaires. Si vous utilisez React, vous pouvez utiliser une bibliothèque de gestion d’état ou un contexte React pour gérer cette instance.
Utiliser la dernière version des SDK appropriés : Utilisez la dernière version des SDK du package npm connect-js ou react-connect-js. Ces SDK initialisent les composants intégrés de manière à optimiser les performances. Des améliorations de performance ont été apportées aux SDK. Nous vous recommandons donc de les mettre à jour si vous utilisez une ancienne version.
Chargez le script connect.js dès que possible dans votre flux : La première possibilité de charger le script est de l’inclure dans votre head HTML. Vous pouvez également utiliser le comportement par défaut de nos SDK de package npm, qui le chargent lors du premier chargement de votre page JavaScript.