Intégration complète de la plateforme Connect

Dans l’exemple ci-dessous, on crée un compte pour lequel Stripe gère les risques, contrôle les tarifs et assume la responsabilité des exigences d’inscription du compte. Votre plateforme utilise des composants intégrés et n’est pas responsable des soldes négatifs. Vos comptes connectés n’ont pas accès aux Dashboards hébergés par Stripe.

Après l’inscription du compte, vous pouvez demander des fonctionnalités supplémentaires, telles que des moyens de paiement spécifiques.

Appelez /v1/accounts avec les paramètres suivants :

• country du compte
• controller.stripe_dashboard.type = none
• demander les fonctionnalités card_payments et transfers

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d country=US \
  -d "controller[stripe_dashboard][type]"=none \
  -d "capabilities[card_payments][requested]"=true \
  -d "capabilities[transfers][requested]"=true

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  "controller": {
    "type": "application",
    "is_controller": true,
    "losses": {"payments": "stripe"},
    "fees": {"payer": "account"},
    "requirement_collection": "stripe",
    "stripe_dashboard": {
      "type": "none",
    },
  },
  "type": "none",
  ...
}

Les comptes connectés accèdent à leurs comptes ainsi qu’aux fonctionnalités de paiement de base directement depuis votre plateforme et n’ont pas accès à un Dashboard hébergé par Stripe. Vous devez fournir l’accès à certaines fonctionnalités par le biais de votre site web.

Votre intégration doit comprendre les composants intégrés suivants :

• Inscription des comptes
• Gestion de compte
• Bannière de notification
• Documents (lorsque Stripe perçoit des frais Stripe directement à partir de comptes connectés)

Votre intégration doit aussi fournir un moyen de répondre aux litiges en fournissant des preuves pour chaque paiement. Pour ce faire, vous pouvez utiliser notre API ou un composant intégré (paiements, informations de paiement ou litiges relatifs à un paiement).

Nous vous recommandons de prévoir un moyen permettant aux comptes connectés d’ajouter des fonds si nécessaire afin d’éviter un solde négatif et de prévenir les interruptions d’activité. Pour ce faire, vous pouvez utiliser un composant intégré (soldes ou virements).

Vous pouvez également ajouter des composants intégrés supplémentaires ou créer vos propres interfaces utilisateur à l’aide de nos API.

Veillez à configurer les composants intégrés avant l’inscription des comptes connectés.

Stripe utilise une session de compte pour exprimer votre intention de fournir un accès aux composants intégrés au compte connecté. À l’aide d’une session de compte, le composant d’inscription de compte intégré collecte toutes les informations requises en fonction des fonctionnalités demandées.

Préremplir les informations du compte

Le composant d’inscription de compte intégré collecte toutes les informations requises en fonction des fonctionnalités demandées.

Vous pouvez simplifier le processus d’inscription en remplissant les champs du compte avec des informations connues avant de créer une session de compte. Préremplissez autant d’informations que possible sur le compte, y compris les informations relatives à l’entreprise, à l’individu et au compte externe, en suivant les étapes ci-dessous :

1. Consultez la documentation sur les informations de vérification requises pour en savoir plus sur la façon dont la combinaison de pays et de fonctionnalités que vous sélectionnez pour les comptes connectés influe sur les exigences.
2. Pour déterminer les informations que Stripe exige d’un compte connecté, récupérez la propriété requirements du compte.
3. Collectez les informations à préremplir.
4. Enregistrez les informations sur le compte en appelant Update Account.

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d business_type=individual \
  --data-urlencode email="jenny.rosen@example.com" \
  -d "individual[first_name]"=Jenny \
  -d "individual[last_name]"=Rosen \
  --data-urlencode "individual[email]"="jenny.rosen@example.com" \
  -d "individual[address][line1]"="354 Oyster Point Blvd" \
  -d "individual[address][city]"="South San Francisco" \
  -d "individual[address][state]"=CA \
  -d "individual[address][postal_code]"=94080 \
  -d external_account=
{{BANK_ACCOUNT_TOKEN_ID}}

Une fois que le compte connecté a terminé l’inscription par le biais du composant intégré d’inscription de compte, votre plateforme ne peut plus mettre à jour certaines informations telles que les comptes de virement ou les informations relatives à l’entité juridique. Le compte connecté doit mettre à jour ces informations, car la plateforme n’est pas responsable des soldes négatifs.

Inscrire des utilisateurs via le composant d’inscription intégré

Les comptes connectés doivent s’inscrire et fournir les informations requises pour activer les paiements et les virements. Pour inscrire un compte connecté, hébergez le composant d’inscription intégré sur votre site Web et redirigez-y les nouveaux comptes.

Créer une session de compte

Lorsque vous créez une session de compte, activez la gestion des comptes en spécifiant account_onboarding dans le paramètre components.

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[account_onboarding][enabled]"=true \
  -d "components[account_onboarding][features][external_account_collection]"=true

Après avoir créé la session de compte et initialisé ConnectJS, vous pouvez afficher le composant d’inscription de compte dans le front-end :

// Include this element in your HTML
const accountOnboarding = stripeConnectInstance.create('account-onboarding');
accountOnboarding.setOnExit(() => {
  console.log('User exited the onboarding flow');
});
container.appendChild(accountOnboarding);

Présentez le flux d’inscription au propriétaire principal du compte. Le propriétaire principal configure l’authentification à Stripe et l’utilisateur peut modifier les informations du compte et réagir en cas de risque. Le compte connecté ne dispose que d’un seul ensemble d’identifiants Stripe. L’utilisateur disposant d’identifiants peut s’authentifier à l’aide de codes temporaires envoyés par SMS pour effectuer des actions plus sensibles, comme mettre à jour les comptes bancaires de destination des virements ou fournir des informations à jour sur l’entité juridique.

Écouter les événements d’inscription

À mesure que le compte avance dans le processus d’inscription, les événements account.updated sont également envoyés à vos webhooks Connect configurés. Lorsque le compte a terminé de renseigner ses informations, le champ details_submitted du compte bascule sur true. Recherchez details_submitted: true dans le corps de l’événement account.updated de votre gestionnaire de webhooks (ou en récupérant l’objet Account) pour vérifier son état. Si details_submitted est défini sur false, affichez à nouveau le composant d’inscription intégré. Si le compte a renseigné des informations, le composant d’inscription intégré collecte uniquement les exigences non soumises.

Lorsqu’un compte connecté envoie ses informations et termine le flux d’inscription, le composant d’inscription intégré appelle le gestionnaire onExit que vous avez défini lors de l’affichage du composant. Utilisez le rappel pour diriger le compte vers la prochaine action. Si vous ne définissez pas de gestionnaire de sortie ou si vous n’intégrez pas d’action à l’intérieur du gestionnaire, le compte reçoit un message d’achèvement sans indication claire de la prochaine étape à suivre.

Étant donné que Stripe gère le risque de crédit et de fraude pour vos comptes connectés, vos comptes doivent être en mesure de voir et de répondre aux alertes de Stripe. Pour faciliter cela, votre plateforme doit intégrer les composants intégrés de bannière de notification et de gestion de compte. Pour plus d’informations sur la façon dont Stripe prend en charge vos comptes connectés par le biais de ces composants, consultez la page relative à l’assistance intégrée pour Connect.

Intégrer la bannière de notification

Stripe utilise le composant intégré de bannière de notification pour informer les comptes connectés des exigences de conformité en attente et d’autres demandes liées aux risques. Répondre à ces notifications permet à un compte de rester en conformité et ainsi de continuer à traiter des paiements et recevoir des virements. Si aucune notification n’est en attente, la bannière de notification intégrée ne s’affiche pas.

Intégrez la bannière de notification à un emplacement bien visible et facilement accessible de votre site Web. Par exemple, vous pouvez l’intégrer en haut de votre page de paiement.

Créer une session de compte

Lorsque vous créez une session de compte, activez la bannière de notification en spécifiant notification_banner dans le paramètre components.

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[notification_banner][enabled]"=true \
  -d "components[notification_banner][features][external_account_collection]"=true

Afficher le composant de bannière de notification

// Include this element in your HTML
const notificationBanner = stripeConnectInstance.create('notification-banner');
container.appendChild(notificationBanner);

// Optional:
// notificationBanner.setCollectionOptions({
//   fields: 'eventually_due',
//   futureRequirements: 'include',
// })

Pour répondre à une bannière de notification, le compte peut cliquer sur un bouton dans la notification. Il n’est pas nécessaire de les rediriger vers le composant intégré de gestion de compte.

Gestion de compte intégrée

Stripe a besoin du composant intégré de gestion de compte pour la gestion des risques. Intégrez ce composant à l’endroit où un compte met à jour ses paramètres ou son profil sur votre site Web.

Créer une session de compte

Lorsque vous créez une session de compte, activez la gestion des comptes en spécifiant account_management dans le paramètre components.

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[account_management][enabled]"=true \
  -d "components[account_management][features][external_account_collection]"=true

Afficher le composant de gestion de compte

// Include this element in your HTML
const accountManagement = stripeConnectInstance.create('account-management');
container.appendChild(accountManagement);

// Optional:
// accountManagement.setCollectionOptions({
//   fields: 'eventually_due',
//   futureRequirements: 'include',
// })

Ce composant permet à un compte de mettre à jour ses informations, de répondre aux exigences de conformité et de mettre à jour ses identifiants d’authentification.

Configurez l’intégration de paiement après avoir intégré les composants requis. Vous pouvez ajouter des composants intégrés pour les paiements et les virements à votre plateforme ou créer vos propres flux.

Configurez les webhooks Connect et écoutez l’événement account.updated. Un compte peut recevoir des paiements lorsque la propriété charges_enabled est définie sur true.

Inclure des paiements et des virements intégrés

Ajoutez les composants de paiement et de virement intégrés à votre plateforme avant de créer votre intégration de paiement. Cela permet au compte d’accéder à ses principaux tunnels de paiement et de les gérer facilement.

Le composant de paiements affiche la liste des paiements du compte connecté et comprend des filtres et des vues détaillées des paiements. Un compte peut émettre des remboursements et répondre aux litiges en fournissant des preuves pour chaque paiement à l’aide de ce composant. Si vous préférez créer et gérer une liste de paiements personnalisée entièrement pilotée par des API, vous pouvez activer les remboursements et les litiges à l’aide du composant d’informations de paiement, du composant de litiges relatifs à un paiement ou de nos API.

Créer une session de compte

Lors de la création d’une session de compte, activez le composant de paiement intégré en spécifiant payments dans le paramètre components. Vous pouvez activer ou désactiver une fonctionnalité du composant de paiement en spécifiant le paramètre features sous payments :

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[payments][enabled]"=true \
  -d "components[payments][features][refund_management]"=true \
  -d "components[payments][features][dispute_management]"=true \
  -d "components[payments][features][capture_payments]"=true \
  -d "components[payments][features][destination_on_behalf_of_charge_management]"=false

Vos comptes connectés peuvent consulter l’ensemble des informations relatives aux paiements directs. Ils peuvent également gérer les remboursements et les litiges et capturer des paiements si vous activez les fonctions correspondantes lors de la création d’une session de compte.

Afficher le composant de paiement

Après avoir créé la session du compte et initialisé ConnectJS, vous pouvez générer le rendu du composant de paiement dans le front-end :

// Include this element in your HTML
const payments = stripeConnectInstance.create('payments');
container.appendChild(payments);

// Optional: specify filters to apply on load
// payments.setDefaultFilters({
//   amount: {greaterThan: 100},
//   date: {before: new Date(2024, 0, 1)},
//   status: ['partially_refunded', 'refund_pending', 'refunded'],
//   paymentMethod: 'card',});

Le composant de virements affiche les virements récents du compte connecté, son solde actuel et la date à laquelle les fonds seront disponibles.

Lors de la création d’une session de compte, activez le composant de virement intégré en spécifiant payouts dans le paramètre components. Vous pouvez activer ou désactiver les fonctionnalités individuelles du composant de virement en spécifiant le paramètre features sous payouts :

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{CONNECTED_ACCOUNT_ID}} \
  -d "components[payouts][enabled]"=true \
  -d "components[payouts][features][instant_payouts]"=true \
  -d "components[payouts][features][standard_payouts]"=true \
  -d "components[payouts][features][edit_payout_schedule]"=true \
  -d "components[payouts][features][external_account_collection]"=true

Après avoir créé la session du compte et initialisé ConnectJS, vous pouvez générer le rendu du composant de virement dans le front-end :

// Include this element in your HTML
const payouts = stripeConnectInstance.create('payouts');
container.appendChild(payouts);

Pour un guide immersif sur la mise en œuvre des composants intégrés, consultez le guide de démarrage rapide sur l’intégration des composants intégrés Connect.

Accepter un paiement

Si vos comptes connectés effectuent des transactions directement avec les clients, utilisez les paiements directs.

Stripe détermine des frais de transaction pour votre plateforme lorsque controller.fees.payer n’est pas défini sur account pour l’objet Account. En retour, vous êtes responsable de l’imputation des frais de traitement des paiements sur vos comptes connectés. Vous pouvez spécifier une valeur de commission de la plateforme pour chaque paiement de manière à débiter automatiquement vos comptes connectés des frais, sans avoir à développer vous-même cet aspect de votre intégration.

Pour accepter les paiements, nous vous recommandons d’utiliser Stripe Checkout, une page préconfigurée hébergée par Stripe. Checkout prend en charge de nombreux moyens de paiement et affiche automatiquement les plus pertinents pour votre client.

Vous pouvez également utiliser le Payment Element, un composant d’interface utilisateur préconfiguré à intégrer qui vous permet d’accepter des moyens de paiement supplémentaires avec une seule intégration.

<html>
  <head>
    <title>Checkout</title>
  </head>
  <body>
    <form action="/create-checkout-session" method="POST">
      <button type="submit">Pay</button>
    </form>
  </body>
</html>

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d mode=payment \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "payment_intent_data[application_fee_amount]"=123 \
  --data-urlencode success_url="https://example.com/success" \
  --data-urlencode cancel_url="https://example.com/cancel"

Stripe communique en votre nom avec vos comptes connectés pour gérer les risques et garantir le maintien de la conformité. Vous pouvez personnaliser et marquer ces communications par e-mail avec votre propre domaine de messagerie et votre propre marque de plateforme.

Nous envoyons les e-mails suivants à vos comptes connectés :

• Les e-mails de compte permettent de vérifier les informations d’un compte telles que les ajouts ou les modifications d’adresses e-mail, de numéro de téléphone ou de compte bancaire.
• Les e-mails relatifs à la conformité demandent aux comptes de fournir les informations requises. Stripe a souvent besoin de collecter des informations supplémentaires pour maintenir sa conformité vis-à-vis de ses partenaires financiers.
• Les e-mails relatifs aux risques informent les comptes lorsqu’ils font l’objet d’un examen des risques. Ces e-mails fournissent souvent des instructions sur la manière de soumettre des informations en vue de la résolution d’une action à risque, par exemple pour lever une suspension des virements.
• Les e-mails fiscaux (uniquement lorsque Stripe perçoit directement des frais Stripe sur les comptes connectés) informent les utilisateurs lorsque leurs factures fiscales, ou formulaires 1099, sont disponibles au téléchargement.

Si vous souhaitez envoyer d’autres e-mails relatifs aux paiements à vos comptes connectés, vous devez les envoyer vous-même. Par exemple, pour envoyer des e-mails concernant de nouveaux litiges, écoutez l’événement charge.dispute.created sur un compte connecté. Lorsque cet événement se produit, utilisez l’API Disputes pour obtenir les détails et les envoyer par e-mail au compte.

Vous devez mettre à jour vos paramètres Connect avec les URL de vos tunnels de paiements et de compte afin que les communications par e-mail de Stripe puissent inclure des liens pour que vos comptes puissent répondre. Vous devez mettre à jour ces liens avant de créer une session de compte ou un lien de compte en mode production.

Gérer les redirections des liens des e-mails

Les e-mails envoyés par Stripe qui contiennent un appel à l’action doivent inclure un lien vers cette action. Par exemple, si nous envoyons un e-mail appelant à l’action sur un compte connecté, il doit inclure un lien vers votre composant de gestion de compte.

Avant de pouvoir créer une session de compte en mode production, vous devez fournir les URL des pages de votre site Web sur lesquelles vous avez intégré les composants. Configurez le domaine de l’e-mail d’envoi et les URL des composants intégrés dans la section Liens vers le site des paramètres de connexion de votre plateforme.

Pour les composants intégrés à votre site, sélectionnez Oui et entrez l’URL de la page qui héberge le composant. Pour toutes les actions qui ne sont pas gérées par un composant intégré, sélectionnez Non et entrez l’URL de la page de votre site où le compte peut effectuer l’action. Après avoir saisi les URL, testez-les pour vérifier qu’elles ouvrent les bonnes pages.

Vous devez définir des URL pour les éléments suivants :

• Bannière de notification
• Gestion de compte
• Paiements
• Virements
• Soldes
• Documents (lorsque Stripe perçoit des frais Stripe directement à partir des comptes connectés)

Lors de l’envoi d’un e-mail, Stripe ajoute automatiquement l’identifiant du compte connecté à l’URL de redirection en tant que paramètre stripe_account_id. Utilisez ce paramètre pour identifier le compte et vérifier qu’il est authentifié. Configurez l’itinéraire sur votre serveur pour lire les paramètres et afficher le composant intégré approprié.

Pour en savoir plus sur la configuration des e-mails envoyés par Stripe à vos comptes connectés, consultez la documentation sur les communications par e-mail dans les intégrations Connect.

Configurer les paramètres et l’adaptation de vos e-mails à votre marque

Stripe peut envoyer des e-mails reflétant les paramètres de la marque de votre plateforme depuis votre propre domaine de messagerie vers vos comptes connectés. Pour configurer les e-mails de Stripe à vos comptes connectés, accédez à la section E-mails du Dashboard de votre plateforme.

À ce stade, vous avez configuré l’intégration de votre plateforme en procédant comme suit :

• Comptes connectés créés avec la configuration adéquate
• Composants intégrés permettant aux comptes connectés de s’inscrire, de gérer leur compte et de répondre aux actions liées aux risques par le biais de votre site Web
• Configurer des paiements à l’aide des paiements directs avec commission de la plateforme
• Configurez la communication par e-mail de votre marque pour permettre à Stripe de transmettre à vos utilisateurs des informations relatives à la conformité, aux actions à risque et aux documents nécessaires.

Tester votre intégration

Testez votre flux de création de comptes en utilisant l’inscription de compte intégrée à votre plateforme. Testez les paramètres de vos moyens de paiement pour vos comptes connectés en vous connectant à l’un de vos comptes test et en accédant aux paramètres des moyens de paiement. Testez votre tunnel de paiement à l’aide de vos clés de test et d’un compte de test. Vous pouvez utiliser nos cartes de test pour tester votre flux de paiement et simuler divers scénarios.