Inscrire vos comptes connectés

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), ou les recueillir progressivement (inscription progressive). L’inscription complète collecte les exigences eventually_due pour le compte, tandis que l’inscription progressive collecte uniquement les exigences currently_due.

Pour déterminer si vous devez utiliser l’inscription complète ou progressive, consultez les exigences 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.

Pour les comptes connectés pour lesquels vous êtes responsable de la collecte des exigences, vous pouvez personnaliser le comportement des exigences futures en utilisant le paramètre collection_options. Pour collecter les exigences futures du compte, définissez collection_options.future_requirements sur include.

Créez un Lien de compte à l’aide de l’ID du compte connecté et incluez une use_case.account_onboarding.refresh_url et une use_case.account_onboarding.return_url.

Stripe redirige le compte connecté vers l’URL d’actualisation si l’URL de connexion au compte a déjà été consultée, a expiré ou est invalide pour toute autre raison. Stripe le redirige vers l’URL de retour lorsqu’il a terminé ou quitté le processus d’onboarding.

De plus, selon que vous souhaitez collecter toutes les informations en amont ou les collecter de manière incrémentielle, transmettez eventually_due ou currently_due dans use_case.account_onboarding.collection_options.fields. Cet exemple transmet eventually_due pour utiliser l’onboarding en amont à la fois pour les exigences currently_due et eventually_due. Pour un onboarding progressif, transmettez currently_due pour collecter uniquement les exigences currently_due en amont.

curl -X POST https://api.stripe.com/v2/core/account_links \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-09-30.preview" \
  --json '{
    "account": 
"{{CONNECTED_ACCOUNT_ID}}",
    "use_case": {
        "type": "account_onboarding",
        "account_onboarding": {
            "configurations": [
                "recipient"
            ],
            "refresh_url": "https://example.com/reauth",
            "return_url": "https://example.com/return"
        }
    }
  }'

Envoyer votre compte connecté vers le processus d’onboarding

Fournissez l’URL du Lien de compte pour envoyer votre compte connecté au processus d’onboarding. Chaque URL de Lien de compte ne peut être utilisée qu’une seule fois, car elle donne accès aux informations personnelles du titulaire du compte.

Configurez votre intégration pour écouter les modifications des exigences du compte. Vous pouvez tester la gestion des nouvelles exigences (et la désactivation des paiements et virements qui peut en résulter) en utilisant les cartes de test dotées de déclencheurs.

Renvoyez un compte connecté via l’inscription lorsqu’il est associé à des exigences currently_due ou eventually_due. Il n’est pas nécessaire d’identifier les exigences spécifiques, car l’interface d’inscription sait quelles informations elle doit collecter. Par exemple, si une faute de frappe empêche la vérification de l’identité du propriétaire du compte, l’inscription invite ce dernier à charger une pièce d’identité.

Stripe vous informe de toute mise à jour des exigences à venir affectant vos comptes connectés. Vous pouvez collecter ces informations de manière proactive en examinant les exigences de vos comptes dont le requested_reasons.code est défini sur future_requirements.

Pour les comptes connectés pour lesquels Stripe est responsable de la collecte des exigences, cessez de recevoir des mises à jour concernant les informations d’identité après avoir créé un lien de compte ou une session de compte.

Les comptes stockent les informations d’identité dans le hachage identity.

Gérer les erreurs de vérification

Écoutez l’événement v2.core.account[requirements].updated. Si le compte contient des exigences avec un minimum_deadline.status de currently_due à l’arrivée de la date limite, la fonctionnalité correspondante est désactivée et ces états deviennent past_due.

Laissez vos comptes remplir les exigences de vérification en les dirigeant vers le formulaire de l’inscription hébergée par Stripe.

Connect onboarding vous demande de transmettre à la fois une return_url et une refresh_url afin de gérer tous les cas de redirection des utilisateurs vers votre plateforme. Il est important que vous les implémentiez correctement afin d’offrir à vos utilisateurs une expérience optimale.

URL de redirection

Stripe redirige le compte connecté vers return_url une fois que l’utilisateur a terminé le processus d’onboarding ou a cliqué sur Sauvegarder pour plus tard à n’importe quelle étape du processus. Cela ne signifie pas que toutes les informations ont été collectées ni qu’il n’y a plus d’exigences en suspens concernant le compte. Cela signifie simplement que le processus a été correctement initié et terminé.

Cette URL ne passe aucun état. Après avoir redirigé un compte connecté vers return_url, déterminez si le compte a terminé l’onboarding soit en :

• Récupération du compte et vérification du hachage requirements pour identifier les exigences en attente.
• Mettre en cache l’état du compte dans votre application et le maintenir à jour en écoutant l’événement v2.core.account[requirements].updated.

Si l’onboarding est incomplet, fournissez des invites dans votre application pour permettre au compte de poursuivre son onboarding ultérieurement.

URL d’actualisation

Stripe redirige l’utilisateur du compte vers refresh_url dans les cas suivants :

• Le lien a expiré (quelques minutes se sont écoulées après la création du lien).
• L’utilisateur a déjà utilisé l’URL (il a actualisé la page ou cliqué sur le bouton Précédent ou Suivant de son navigateur).
• Votre plateforme n’est plus en mesure d’accéder au compte.
• Le lien a été partagé dans une application tierce, comme un client de messagerie, qui tente d’accéder à l’URL pour afficher un aperçu. De nombreux clients visitent automatiquement les liens, ce qui entraîne leur expiration.
• Le compte a été rejeté.

Configurez refresh_url pour exécuter une méthode sur votre serveur afin de créer un nouveau Lien de compte avec les mêmes paramètres, puis redirigez le compte connecté vers la nouvelle URL du Lien de compte.

Un utilisateur du compte qui est redirigé vers votre return_url peut ne pas avoir terminé le processus d’onboarding. Utilisez l’endpoint /v2/core/accounts pour récupérer l’Account et vérifier si configuration.recipient.capabilities.stripe_balance.stripe_transfers.status est active. Si l’état n’est pas active et configuration.recipient.capabilities.stripe_balance.stripe_transfers.status_details.code est requirements_past_due, fournissez des invites d’interface utilisateur pour permettre à l’utilisateur du compte de poursuivre l’onboarding via un nouveau Lien de compte. Gérez d’autres codes si nécessaire.

L’onboarding hébergé par Stripe prend également en charge les mises à jour initiées par le compte connecté des informations qu’il a déjà fournies. Écoutez l’événement v2.core.account[requirements].updated envoyé à votre endpoint webhook pour être notifié lorsque le compte remplit les exigences.

Lorsque vous créez un Lien de compte, définissez le type sur account_onboarding. Les Liens de compte de ce type fournissent un formulaire pour saisir toutes les exigences en attente. Utilisez-le lorsque vous effectuez l’onboarding d’un nouveau compte connecté, ou lorsqu’un compte existant a de nouvelles exigences (comme lorsque vous demandez une nouvelle fonctionnalité qui a besoin d’informations supplémentaires).