Accéder directement au contenu
Créez un compte
 ou
connecter-vous
Logo de la documentation Stripe
/
Créez un compte
Connectez-vous

Premiers pas avec les composants intégrés Connect

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

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

main.rb
require 'sinatra'
require 'stripe'
# This is a placeholder - it should be replaced with your secret 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.
Stripe.api_key = 
'sk_test_4eC39HqLyjWDarjtT1zdp7dc'


post '/account_session' do
  content_type 'application/json'

  # Create an AccountSession
  begin
    account_session = Stripe::AccountSession.create({
      account: 
'{{CONNECTED_ACCOUNT_ID}}'
,
      components: {
        payments: {
          enabled: true,
          features: {
            refund_management: true,
            dispute_management: true,
            capture_payments: true
          }
        }
      }
    })

    {
      client_secret: account_session[:client_secret]
    }.to_json
  rescue => error
    puts "An error occurred when calling the Stripe API to create an account session: #{error.message}";
    return [500, { error: error.message }.to_json]
  end
end

Create Account Session API

The Create Account Session API determines component and feature access for Connect embedded components. Stripe enforces these parameters for any components that correspond to the account session. If your site supports multiple user roles, make sure components and features that are enabled for that account session correspond to the current user’s role. For example, you can enable refund management only for administrators of your site, but not for other users. To ensure user role access are enforced, your backend must host the logic that maps your site’s user role to account session components.

Configurer Connect.js Client

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.

index.html
<head>
  <script type="module" src="index.js" defer></script>
</head>
<body>
  <h1>Payments</h1>
  <div id="container"></div>
  <div id="error" hidden>Something went wrong!</div>
</body>
index.js
import {loadConnectAndInitialize} from '@stripe/connect-js';

const fetchClientSecret = async () => {
  // Fetch the AccountSession client secret
  const response = await fetch('/account_session', { method: "POST" });
  if (!response.ok) {
    // Handle errors on the client side here
    const {error} = await response.json();
    console.error('An error occurred: ', error);
    document.querySelector('#error').removeAttribute('hidden');
    return undefined;
  } else {
    const {client_secret: clientSecret} = await response.json();
    document.querySelector('#error').setAttribute('hidden', '');
    return clientSecret;
  }
}

const stripeConnectInstance = loadConnectAndInitialize({
    // 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 paymentComponent = stripeConnectInstance.create("payments");
const container = document.getElementById("container");
container.appendChild(paymentComponent);

Consulter la liste complète des composants intégrés pris en charge →

Configurer Connect.js
Côté client

La méthode loadConnectAndInitialize côté client nécessite plusieurs options pour configurer Connect.js.

OptionDescription
publishableKeyLa clé publiable de votre intégration.obligatoire
fetchClientSecretFonction 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
appearanceObjet permettant de personnaliser l’apparence des composants intégrés Connect.facultatif
localeParamè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 indiquée n’est pas directement prise en charge, un paramètre similaire est utilisé (par exemple, fr-fr peut être utilisé à la place de fr-be). Rendez-vous dans la section localisation pour consulter la liste des langues prises en charge.facultatif
fontsUn 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.

index.js
const fetchClientSecret = async () => {
  const response = await fetch('/account_session');
  const {client_secret: clientSecret} = await response.json();
  return clientSecret;
}

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",
    },
  },
});

L’objet polices

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 apparence

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 :

index.js
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.

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');
  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.

index.js
// 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 :

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

Localisation

Lors de l’initialisation de Connect.js, vous pouvez transmettre un paramètre locale. Pour que la langue d’un composant intégré et la langue de votre site Web correspondent, transmettez le paramètre locale avec la langue de l’interface utilisateur de votre site Web.

La valeur par défaut du paramètre locale est déterminée par la langue configurée par le navigateur. Si la langue spécifiée n’est pas directement prise en charge, une alternative est utilisée (par exemple, fr-be peut être remplacé par fr-fr).

Les composants intégrés Connect prennent en charge les paramètres locaux suivants :

LangueCode 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

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.

index.js
// Load errors are emitted by all components. We use Balances as an example here.
const balances = stripeConnectInstance.create('balances');
balances.setOnLoadError((loadError) => {
  const componentName = loadError.elementTagName
  const error = loadError.error

  console.log(componentName + " failed to load")
  console.log(`${error.type}: ${error.message}`);
});

container.appendChild(balances);
MethodDescriptionVariables
setOnLoadErrorThe component executes this callback function when a load failure occurs.
  • loadError.error: See the load error object
  • loadError.elementTagName: The name of HTML tag used to render the component in the browser

The load error object

Every time there’s a load failure, an error object is passed to the load error handler with the following properties.

Name
Type
Example value
type
See types of load failures
authentication_error
The type of error
message
string | undefined
Failed to fetch account session
Further description about the error

Types of load failures

When a component fails to load, we detect the type of failure and map it to one of the types below. If the load error type can’t be determined it is marked as an api_error.

TypeDescription
api_connection_errorFailure to connect to Stripe’s API
authentication_errorFailure to perform the authentication flow within Connect embedded components
account_session_create_errorAccount session creation failed
invalid_request_errorRequest failed with an 4xx status code, typically caused by platform configuration issues
rate_limit_errorRequest failed because an abnormal request rate was detected
api_errorAPI errors covering any other type of problem, such as a temporary problem with Stripe’s servers

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 des fenêtres contextuelles une fois leur chargement terminé. Pour éviter cela, affichez votre propre interface utilisateur de chargement avant la création du composant et masquez l’interface après l’affichage du composant. Tous les composants intégrés peuvent accepter une fonction de rappel qui est appelée immédiatement avant que l’interface utilisateur ne soit présentée à l’utilisateur.

index.html
<span id="spinner"></span>
<div id="balances-container"></div>
index.js
// Loader start events are emitted by all components. We use Balances as an example here.
const container = document.getElementById('balances-container');
const balances = stripeConnectInstance.create('balances');

balances.setOnLoaderStart((event) => {
  container.getElementById("spinner").display = "none";
  console.log(`${event.elementTagName} is visible to users`)
});

container.appendChild(balances);
MethodDescriptionVariables
setOnLoaderStartThe component executes this callback function before any UI is displayed to the user.
  • event.elementTagName: The name of HTML tag used to render the component in the browser

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.

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 de Connect ne requièrent généralement pas d’authentification de l’utilisateur. Dans certains cas, les composants intégrés de Connect nécessitent que le compte connecté s’identifie avec son compte Stripe pour 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).

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 :

D’autres composants peuvent nécessiter une authentification interne après l’affichage initial. Pour ces composants et scénarios, l’authentification est requise pour les comptes connectés dont Stripe est responsable de la collecte des informations à jour en cas d’évolution des exigences. Dans le cas des comptes connectés pour lesquels vous êtes responsable de la collecte des informations à jour, l’authentification Stripe est contrôlée par la fonctionnalité disable_stripe_user_authentication Account Session. Nous vous recommandons de mettre en place l’authentification à deux facteurs ou des mesures de sécurité équivalentes en guise de bonne pratique. Pour les configurations de compte qui prennent en charge cette fonctionnalité, comme Custom, vous assumez la responsabilité des comptes connectés en cas d’impossibilité de rembourser les soldes négatifs.

Cette page vous a-t-elle été utile ?
OuiNon
Besoin d'aide ? Contactez le service d'assistance.
Rejoignez notre programme d'accès anticipé.
Consultez notre journal des modifications des produits.
Des questions ? Contactez l'équipe commerciale.
Propulsé par Markdoc
Sur cette page
Initialiser Connect.js
Créer une AccountSession
Create Account Session API
Configurer Connect.js
Charger et initialiser Connect.js
Configurer Connect.js
Personnaliser l’apparence des composants intégrés Connect
L’objet polices
L’objet apparence
Mettre à jour les composants intégrés Connect après l’initialisation
Largeur et hauteur
Authentification
Actualiser la clé secrète du client
Se déconnecter
Exigences relatives aux en-têtes CSP et HTTP
Navigateurs pris en charge
Localisation
Traiter les erreurs de chargement
Détecter l’affichage de composants intégrés
Intégration sans paquet NPM front-end
Utilisation de Connect.js without NPM
Authentification de l’utilisateur dans les composants intégrés de Connect
Produits utilisés
Connect