# Inscription des utilisateurs via l'API Créez votre propre flux d'inscription des utilisateurs à l'aide des API de Stripe. Avec l’API Onboarding, vous utilisez l’API Accounts pour créer un flux d’inscription, une fonctionnalité de reporting et des canaux de communication pour vos utilisateurs. Stripe peut être totalement invisible pour le titulaire du compte. Cependant, votre plateforme est responsable de toutes les interactions avec vos comptes et de la collecte de toutes les informations nécessaires à leur vérification. > #### Responsabilités supplémentaires > > Avec l’inscription via l’API, votre flux personnalisé doit répondre à toutes les exigences légales et réglementaires en vigueur dans les régions où vous exercez vos activités. Vous devez également consacrer des ressources au suivi des modifications apportées à ces exigences et recueillir des informations mises à jour de manière continue, au moins une fois tous les six mois. Si vous souhaitez mettre en place un flux d’inscription personnalisé, Stripe vous conseille vivement d’utiliser l’[inscription intégrée](https://docs.stripe.com/connect/embedded-onboarding.md). (See full diagram at https://docs.stripe.com/connect/api-onboarding) ## Définir des exigences Les facteurs suivants affectent les [exigences d’inscription](https://docs.stripe.com/connect/required-verification-information.md) pour vos comptes connectés : - Pays d’origine des comptes connectés - Le [type de contrat de service](https://docs.stripe.com/connect/service-agreement-types.md) applicable aux comptes connectés - [Fonctionnalités](https://docs.stripe.com/connect/account-capabilities.md) demandées pour les comptes connectés - Le [business_type](https://docs.stripe.com/api/accounts/object.md#account_object-business_type) (par exemple, particulier ou entreprise) et la [structure de l’entreprise](https://docs.stripe.com/api/accounts/object.md#account_object-company-structure) (par exemple, `public_corporation` ou `private_partnership`) Utilisez les [Informations de vérification requises](https://docs.stripe.com/connect/required-verification-information.md) pour voir comment la modification de ces facteurs affecte les exigences d’inscription des utilisateurs pour vos comptes connectés. ## Créer des formulaires pour collecter des informations [Côté client] Il est recommandé d’organiser les paramètres requis en groupes logiques ou en formulaires dans votre flux d’inscription. Vous pouvez coder un mappage entre les paramètres Stripe et les regroupements logiques. Les regroupements logiques suggérés pour les paramètres sont indiqués dans la première colonne de l’exemple de tableau des exigences. Après avoir encodé les paramètres requis au sein de votre application, générez des interfaces utilisateur pour les paramètres correspondant à ces exigences. Pour chaque paramètre, créez un formulaire d’interface utilisateur qui comprend : - Libellé de paramètre, localisé dans chaque pays et langue pris en charge - Description des paramètres, localisée dans chaque pays et langue pris en charge - Champs de saisie des paramètres avec logique de validation des données et chargement de documents au besoin Il est important de structurer votre logique d’application pour prendre en compte la possibilité d’ajouter des paramètres ultérieurement. Par exemple, Stripe peut introduire de nouveaux paramètres, de nouvelles vérifications ou de nouveaux seuils que vous devez intégrer dans vos flux d’inscription au fil du temps. Si vous modifiez l’un des facteurs qui déterminent les exigences de vos comptes connectés, vous devez également adapter vos formulaires de collecte pour tenir compte des nouvelles exigences. Le [pays](https://docs.stripe.com/api/accounts/object.md#account_object-country) et le [type de contrat de service](https://docs.stripe.com/api/accounts/object.md#account_object-tos_acceptance-service_agreement) sont non mutables, tandis que les [fonctionnalités](https://docs.stripe.com/api/accounts/object.md#account_object-capabilities) et le [type d’entreprise](https://docs.stripe.com/api/accounts/object.md#account_object-business_type) sont mutables. - Pour modifier un champ non mutable, créez un nouveau compte connecté avec les nouvelles valeurs pour remplacer le compte existant. - Pour modifier un champ mutable, mettez à jour le compte connecté. ### Inclure les Conditions d’utilisation du service Stripe Vos comptes connectés doivent accepter les Conditions d’utilisation du service Stripe avant de pouvoir être activés. Vous pouvez [inclure les Conditions d’utilisation du service Stripe aux vôtres](https://docs.stripe.com/connect/updating-service-agreements.md#adding-stripes-service-agreement-to-your-terms-of-service). ## Créer un compte connecté [Côté serveur] Créez un [compte](https://docs.stripe.com/api/accounts/create.md) dans lequel votre plateforme est responsable des soldes négatifs, dans lequel Stripe perçoit des frais sur votre compte de plateforme et dans lequel vos comptes connectés n’ont pas accès à un Dashboard hébergé par Stripe. Demandez toutes les fonctionnalités dont vos comptes connectés ont besoin. Préremplissez le type d’entreprise et toute autre information disponible correspondant à vos [besoins](https://docs.stripe.com/connect/api-onboarding.md#establish-requirements). Vous pouvez également créer un compte connecté dont le `type` est défini sur `custom`, avec les fonctionnalités de votre souhait. Si vous ne spécifiez pas le pays ni le contrat de type de service, les valeurs par défaut suivantes leur sont attribuées : - Le `country` par défaut est le même pays que celui de votre plateforme. - Le contrat de type de service (`tos_acceptance.service_agreement`) est défini sur `full` par défaut. > Pour se conformer à la réglementation DSP2 française, les plateformes françaises [doivent utiliser des tokens de compte](https://stripe.com/guides/frequently-asked-questions-about-stripe-connect-and-psd2#regulatory-status-of-connect). Les tokens présente un autre avantage : ils évitent à la plateforme de stocker des éléments d’identification, qui sont transférés du compte connecté directement à Stripe. Nous recommandons également aux plateformes situées dans d’autres pays d’utiliser des tokens de compte, mais ce n’est pas obligatoire. #### Avec les propriétés du contrôleur ```curl curl https://api.stripe.com/v1/accounts \ -u "<>:" \ -d "controller[losses][payments]=application" \ -d "controller[fees][payer]=application" \ -d "controller[stripe_dashboard][type]=none" \ -d "controller[requirement_collection]=application" \ -d "capabilities[card_payments][requested]=true" \ -d "capabilities[transfers][requested]=true" \ -d business_type=individual \ -d country=US ``` #### Avec un type de compte ```curl curl https://api.stripe.com/v1/accounts \ -u "<>:" \ -d type=custom \ -d "capabilities[card_payments][requested]=true" \ -d "capabilities[transfers][requested]=true" \ -d business_type=individual \ -d country=US ``` ## Déterminer les informations à collecter [Côté serveur] En tant que plateforme, vous devez décider entre collecter toutes les informations requises auprès de vos comptes connectés au début du processus *(inscription complète)* (Upfront onboarding is a type of onboarding where you collect all required verification information from your users at sign-up), ou les recueillir progressivement *(inscription progressive)* (Incremental onboarding is a type of onboarding where you gradually collect required verification information from your users. You collect a minimum amount of information at sign-up, and you collect more information as the connected account earns more revenue). L’inscription complète collecte les exigences `eventually_due` pour le compte, tandis que l’inscription progressive collecte uniquement les exigences `currently_due`. | Type d’inscription | Avantages | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | \**En amont ** | - Ne nécessite normalement qu’une seule requête pour l’ensemble des informations - Évite les problèmes de paiement et de traitement dus au non-respect des délais - Permet de détecter en amont les risques potentiels lorsque les clients refusent de communiquer des informations | | **Progressive** | - Les comptes peuvent s’inscrire rapidement parce qu’ils n’ont pas à fournir autant d’informations | Pour déterminer si vous devez utiliser l’inscription complète ou progressive, consultez les [exigences](https://docs.stripe.com/connect/required-verification-information.md) relatives aux emplacements et aux fonctionnalités de vos comptes connectés. Stripe s’efforce de minimiser son impact sur les comptes connectés, cependant, les exigences sont susceptibles d’évoluer. Dans le cas des comptes connectés pour lesquels vous êtes responsable de la collecte des exigences, vous pouvez personnaliser le comportement des [exigences futures](https://docs.stripe.com/connect/handle-verification-updates.md) à l’aide du paramètre `collection_options`. Pour collecter les futurs besoins du compte, définissez [`collection_options.future_requirements`](https://docs.stripe.com/api/account_links/create.md#create_account_link-collection_options-future_requirements) sur `include`. ### Collecter des informations publiques supplémentaires (Private preview) Stripe collecte les informations publiques obligatoires pour chaque compte connecté. Vous pouvez sélectionner des champs supplémentaires à collecter lors de l’onboarding en fonction des besoins de votre activité. Tous les champs que vous choisissez et que Stripe ne requiert pas apparaissent comme facultatifs, et les comptes connectés peuvent décider s’ils souhaitent les fournir. 1. Dans les paramètres [Informations publiques](https://dashboard.stripe.com/settings/connect/onboarding-options/public-details) du Dashboard, activez le bouton **Collecter les informations publiques**. 1. Sélectionnez les champs à afficher aux comptes connectés lors de l’onboarding. 1. Cliquez sur **Enregistrer**. #### Champs disponibles Vous pouvez collecter les informations publiques suivantes : | Champ | Description | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | [Libellé de relevé bancaire](https://docs.stripe.com/connect/statement-descriptors.md) | Le texte qui apparaît sur la carte bancaire ou les relevés bancaires du client pour les paiements effectués vers le compte connecté. | | Numéro de téléphone du service de support client | Un numéro de téléphone que les clients peuvent appeler pour obtenir de l’assistance concernant le compte connecté. | | Adresse du service de support client | Une adresse postale que les clients peuvent utiliser pour contacter le compte connecté. | | Adresse e-mail du service de support | Une adresse e-mail que les clients peuvent utiliser pour contacter le compte connecté. | > #### Les exigences varient > > Les exigences de Stripe varient selon le compte connecté, en fonction du type de l’entreprise, du pays et des fonctionnalités demandées. Activez les champs pour vous assurer qu’ils apparaissent toujours lors de l’onboarding, qu’ils soient requis ou non. Pour mettre en œuvre votre stratégie d’inscription, inspectez le hachage des exigences du compte connecté que vous avez créé. Le hachage requirements fournit une liste complète des informations que vous devez collecter pour activer le compte connecté. - Pour l’inscription progressive, examinez le hachage `currently_due` dans le hachage des exigences et créez un flux d’inscription qui collecte uniquement ces exigences. - Pour l’inscription complète, vérifiez les hachages `currently_due` et `eventually_due` dans le hachage des exigences et créez un flux d’inscription qui collecte ces exigences. ```json { ... "requirements": { "alternatives": [], "current_deadline": null, "currently_due": [ "business_profile.product_description", "business_profile.support_phone", "business_profile.url", "external_account", "tos_acceptance.date", "tos_acceptance.ip" ], "disabled_reason": "requirements.past_due", "errors": [],"eventually_due": [ "business_profile.product_description", "business_profile.support_phone", "business_profile.url", "external_account", "tos_acceptance.date", "tos_acceptance.ip" ], "past_due": [], "pending_verification": [] }, ... } ``` ## Gérer les exigences en matière de preuves d'existence Un compte peut comporter un ou plusieurs objets [Person](https://docs.stripe.com/api/persons.md) avec une exigence `proof_of_liveness`. Une exigence `proof_of_liveness` peut impliquer la collecte d’un identifiant électronique, tel que [MyInfo](https://www.singpass.gov.sg/main/individuals/) à Singapour, ou l’utilisation de Stripe Identity pour collecter un document ou un selfie.Nous recommandons d’utiliser l’onboarding hébergé ou embarqué par Stripe afin de répondre à toutes les variantes de l’exigence `proof_of_liveness`. #### Hébergé [L’inscription des utilisateurs hébergée par Stripe](https://docs.stripe.com/connect/hosted-onboarding.md) permet de répondre à toutes les formes d’exigences `proof_of_liveness`. [Créez un lien de compte](https://docs.stripe.com/connect/hosted-onboarding.md#create-account-link) à l’aide de l’ID de compte connecté et envoyez le compte à l’`url` renvoyée. ```curl curl https://api.stripe.com/v1/account_links \ -u "<>:" \ -d "account={{CONNECTEDACCOUNT_ID}}" \ --data-urlencode "refresh_url=https://example.com/refresh" \ --data-urlencode "return_url=https://example.com/return" \ -d type=account_onboarding \ -d "collection_options[fields]=currently_due" ``` Le compte reçoit un message l’invitant à répondre à l’exigence `proof_of_liveness`, ainsi qu’à toute autre exigence devant être satisfaite. Écoutez l’événement `account.updated` envoyé à votre endpoint de webhook pour recevoir une notification lorsque le compte satisfait aux exigences et met à jour ses informations. Une fois que le compte est en règle, il est redirigé vers la `return_url` spécifiée. #### Intégrés [L’intégration intégrée](https://docs.stripe.com/connect/embedded-onboarding.md) permet de répondre à toutes les formes d’exigences `proof_of_liveness`. Lorsque vous [créez une session de compte](https://docs.stripe.com/api/account_sessions/create.md), activez l’inscription des comptes en spécifiant `account_onboarding` dans le paramètre `components`. Si vous n’avez pas besoin de collecter les informations du compte bancaire, désactivez `external_account_collection`. Cela s’applique généralement aux plateformes Connect qui souhaitent avoir recours à des prestataires de collecte de comptes externes tiers. ```curl curl https://api.stripe.com/v1/account_sessions \ -u "<>:" \ -d "account={{CONNECTEDACCOUNT_ID}}" \ -d "components[account_onboarding][enabled]=true" \ -d "components[account_onboarding][features][external_account_collection]=false" ``` Après avoir créé la session de compte et [initialisé ConnectJS](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#account-sessions), vous pouvez afficher le composant d’inscription de compte dans le front-end : #### JavaScript ```js // Include this element in your HTML const accountOnboarding = stripeConnectInstance.create('account-onboarding'); accountOnboarding.setOnExit(() => { console.log('User exited the onboarding flow'); }); container.appendChild(accountOnboarding); // Optional: make sure to follow our policy instructions above // accountOnboarding.setFullTermsOfServiceUrl('{{URL}}') // accountOnboarding.setRecipientTermsOfServiceUrl('{{URL}}') // accountOnboarding.setPrivacyPolicyUrl('{{URL}}') // accountOnboarding.setCollectionOptions({ // fields: 'eventually_due', // futureRequirements: 'include', // requirements: { // exclude: ['business_profile.product_description'] // } // }) // accountOnboarding.setOnStepChange((stepChange) => { // console.log(`User entered: ${stepChange.step}`); // }); ``` Le compte reçoit un message l’invitant à répondre à l’exigence `proof_of_liveness`, ainsi qu’à toute autre exigence devant être satisfaite. Écoutez l’événement `account.updated` envoyé à votre endpoint de webhook pour recevoir une notification lorsque le compte satisfait aux exigences, ConnectJS appelle votre gestionnaire JavaScript `onExit`. #### Identity Vous pouvez utiliser [Stripe Identity](https://docs.stripe.com/identity.md) pour remplir une exigence de `proof_of_liveness` sur un objet `Person` en collectant un document et un selfie. [Créer une session de vérification](https://docs.stripe.com/api/identity/verification_sessions/create.md). Spécifiez le paramètre `related_person` pour associer les données de vérification collectées à l’objet `Person` qui requiert la `proof_of_liveness`, comme le montre l’exemple suivant. ```curl curl https://api.stripe.com/v1/identity/verification_sessions \ -u "<>:" \ -d type=document \ -d "options[document][require_matching_selfie]=true" \ -d "related_person[account]={{CONNECTEDACCOUNT_ID}}" \ -d "related_person[person]={{PERSON_ID}}" ``` Une fois la `VerificationSession` créée, utilisez le `client_secret` renvoyé pour [afficher la fenêtre modale Identity à l’utilisateur](https://docs.stripe.com/identity/verify-identity-documents.md?platform=web&type=modal#show-modal) ou rediriger l’utilisateur vers l’adresse `URL`. La fin de la vérification met automatiquement le compte à jour. Nous envoyons un événement `account.updated` à votre endpoint de webhook lorsque le compte termine la vérification d’identité et met à jour ses informations. ## Mettre à jour le compte connecté [Côté serveur] [Mettez à jour l’objet Account](https://docs.stripe.com/api/accounts/update.md) avec de nouvelles informations à chaque étape du flux d’inscription de votre compte connecté. Cela permet à Stripe de valider les informations dès qu’elles sont ajoutées. Une fois que Stripe a confirmé son acceptation de nos conditions d’utilisation du service, toute modification apportée à l’objet `Account` déclenche une revérification. Par exemple, si vous modifiez le nom et le numéro d’identification du compte connecté, Stripe relance les vérifications. ```curl curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}} \ -u "<>:" \ --data-urlencode "business_profile[url]=https://furever.dev" \ -d "tos_acceptance[date]=1609798905" \ -d "tos_acceptance[ip]=8.8.8.8" ``` Lors de la mise à jour d’un compte connecté, vous devez gérer les [erreurs de vérification](https://docs.stripe.com/connect/api-onboarding.md#handle-verification-errors) ou les [codes d’erreur HTTP](https://docs.stripe.com/error-handling.md). ## Gérer les erreurs de vérification [Côté serveur] Lorsque les données du compte connecté sont soumises, Stripe les vérifie. Ce processus peut prendre quelques minutes ou quelques heures, selon la nature de la vérification. Au cours de ce processus, les fonctionnalités que vous avez demandées ont pour `status` `pending`. ### État de la vérification Vous pouvez récupérer l’état des fonctionnalités de votre compte connecté des manières suivantes : - Examen du hash des [fonctionnalités](https://docs.stripe.com/api/accounts/object.md#account_object-capabilities) de l’objet Account pour la fonctionnalité concernée. - Demandez des fonctionnalités directement à partir de l’[API Capabilities](https://docs.stripe.com/api/capabilities/retrieve.md) et examinez l’état de la fonctionnalité concernée. - Écoutez les [événements](https://docs.stripe.com/api/events/types.md#event_types-account.updated) `account.updated` dans votre endpoint de [webhook](https://docs.stripe.com/connect/webhooks.md) et inspectez le hash `capabilities` pour la fonctionnalité correspondante. Une fois les vérifications terminées, une fonctionnalité devient `active` et disponible pour le compte connecté. Les vérifications de compte s’exécutent en permanence, et si une vérification ultérieure échoue, une fonctionnalité peut ne plus être `active` . Écoutez les événements `account.updated` pour détecter les changements d’état des fonctionnalités. Confirmez que votre intégration Connect est conforme et opérationnelle en vérifiant que les paramètres `charges_enabled` et `payouts_enabled` du compte sont tous deux définis sur « true ». Vous pouvez utiliser l’API ou écouter les événements `account.updated`. Pour plus d’informations sur les autres champs pertinents, vérifiez le hash des [exigences](https://docs.stripe.com/api/accounts/object.md#account_object-requirements) du compte. Vous ne pouvez pas confirmer l’intégration sur la base d’une seule valeur, car les états peuvent varier selon l’application et les politiques associées. - [charges_enabled](https://docs.stripe.com/api/accounts/object.md#account_object-charges_enabled) confirme que votre chemin de paiement complet (paiement et transfert) fonctionne correctement et détermine si les fonctions `card_payments` et `transfers` sont actives. - [payouts_enabled](https://docs.stripe.com/api/accounts/object.md#account_object-payouts_enabled) détermine si votre compte connecté peut effectuer des virements vers un compte externe. En fonction de vos politiques en matière de risques, vous pouvez autoriser votre compte connecté à commencer à effectuer des transactions sans avoir activé les virements. À terme, vous [devrez activer les virements](https://docs.stripe.com/connect/manage-payout-schedule.md) pour verser des fonds sur vos comptes connectés. Vous pouvez partir de la logique suivante pour définir un état récapitulatif à afficher pour votre compte connecté. #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. client = Stripe::StripeClient.new('<>') def account_state(account) reqs = account.requirements if reqs.disabled_reason && reqs.disabled_reason.include?("rejected") "rejected" elsif account.payouts_enabled && account.charges_enabled if reqs.pending_verification "pending enablement" elsif !reqs.disabled_reason && !reqs.currently_due if !reqs.eventually_due "complete" else "enabled" end else "restricted" end elsif !account.payouts_enabled && account.charges_enabled "restricted (payouts disabled)" elsif !account.charges_enabled && account.payouts_enabled "restricted (charges disabled)" elsif reqs.past_due "restricted (past due)" elsif reqs.pending_verification "pending (disabled)" else "restricted" end end accounts = client.v1.accounts.list({limit: 10}) accounts.each do |account| puts "#{account.id} has state: #{account_state(account)}" end ``` > Vous ne pouvez pas utiliser l’API pour répondre aux vérifications des risques de Stripe. Vous pouvez autoriser vos comptes connectés à répondre à l’aide de composants intégrés, d’une procédure d’inscription hébergée par Stripe ou de liens de rectification. Vous avez également la possibilité d’utiliser le Dashboard pour répondre à des vérifications des risques au nom de vos comptes connectés. Écoutez l’événement [account.updated](https://docs.stripe.com/api/events/types.md#event_types-account.updated). Si le compte contient des champs `currently_due` à l’arrivée de la date `current_deadline`, la fonctionnalité correspondante est désactivée et ces champs sont ajoutés à `past_due`. [Créez un formulaire](https://docs.stripe.com/connect/api-onboarding.md#create-forms-to-collect-information) donnant des instructions claires que le compte pourra utiliser pour corriger ses informations. Informez le compte, puis [soumettez les informations corrigées](https://docs.stripe.com/connect/api-onboarding.md#update-the-connected-account) à l’aide de l’API Accounts. (See full diagram at https://docs.stripe.com/connect/api-onboarding) Si vous prévoyez de créer des flux personnalisés pour gérer l’ensemble de vos erreurs de vérification : - Consultez les informations concernant toutes les [erreurs de vérification possibles et comment les gérer](https://docs.stripe.com/connect/handling-api-verification.md). - [Tester les états de vérification](https://docs.stripe.com/connect/testing-verification.md).