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_VePHdqKTYQjKNInc7u56JBrQ'

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

Set up Connect.js Client

Install the npm package to use Connect.js as a module.

Command Line

npm install --save @stripe/connect-js

Load and initialize Connect.js Client

Call loadConnectAndInitialize with your publishable key and a function that retrieves a client secret by calling the new endpoint you created on your server. Use the returned StripeConnectInstance to create embedded components. After initializing Connect.js, you can mount components to or unmount components from the DOM at any time. That includes any elements rendered inside React or Vue portals.

To create a component, call create on the StripeConnectInstance that you created above, then pass in the component name. This returns a custom element that Connect.js registers and uses to automatically wire your DOM up to Stripe. You can then append this element to your DOM.

Call create with payments, then add the result to your DOM to render a payments UI.

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_oKhSR5nslBRnBZpjO6KuzZeX",
    fetchClientSecret: fetchClientSecret,
  });
const paymentComponent = stripeConnectInstance.create("payments");
const container = document.getElementById("container");
container.appendChild(paymentComponent);

See a complete list of supported embedded components →

Configurer Connect.js
Cô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.

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_oKhSR5nslBRnBZpjO6KuzZeX",
  fetchClientSecret: fetchClientSecret,
  fonts: [
    {
      cssSrc: "https://myfonts.example.com/my-font-1",
    },
    {
      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 `fonts`

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

CssFontSource

CustomFontSource

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"}`
See the full list of appearance variables.

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 :

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

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`

Integrate without frontend npm packages

We recommend integrating with our javascript and React component wrappers, which simplify the loading of Connect embedded components and provide TypeScript definitions for our supported interfaces. If your build system currently doesn’t support taking a dependency on packages, you can integrate without these packages.

Manually add the Connect.js script tag to the <head> of each page on your site.

<!-- Somewhere in your site's <head> -->
<script src="https://connect-js.stripe.com/v1.0/connect.js" async></script>

Using Connect.js without NPM

After Connect.js completes loading, it initializes the global window variable StripeConnect and calls StripeConnect.onLoad if you define it. You can safely initialize Connect.js by setting up an onload function and calling StripeConnect.init with the same Connect.js options as 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_oKhSR5nslBRnBZpjO6KuzZeX",
      fetchClientSecret: fetchClientSecret,
    });

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

Premiers pas avec les composants intégrés Connect

Initialiser Connect.jsCôté clientCôté serveur

Créer une AccountSession Server

Set up Connect.js Client

Load and initialize Connect.js Client

Configurer Connect.jsCôté client

Personnaliser l’apparence des composants intégrés Connect

L’objet fonts

CssFontSource

CustomFontSource

L’objet appearance

Mettre à jour les composants intégrés Connect après l’initialisation

Note

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

Langues prises en charge

Integrate without frontend npm packages

Using Connect.js without NPM

Initialiser Connect.js
Côté client
Côté serveur

Configurer Connect.js
Côté client

L’objet `fonts`

L’objet `appearance`