# Réassociez les comptes Financial Connections utilisés pour les paiements ou les virements. Réactivez les comptes inactifs pour récupérer les données, réactivez les numéros de compte tokenisés et mettez à jour les autorisations d’accès aux données. Vos clients peuvent avoir besoin de réautoriser un [compte Financial Connections](https://docs.stripe.com/api/financial_connections/accounts/object.md) précédemment associé pour [plusieurs raisons](https://docs.stripe.com/financial-connections/relink.md), telles que la réactivation d’un compte pour rétablir l’accès aux données ou l’actualisation des [numéros de compte tokenisés](https://docs.stripe.com/financial-connections/tokenized-account-numbers.md) désactivés. Lorsque vous utilisez des comptes Financial Connections pour vérifier les informations du compte bancaire en vue de paiements ou de virements, configurez une session de réassociation pour collecter un seul compte éligible. Vous pouvez : - [Réassocier un compte Financial Connections spécifique](https://docs.stripe.com/financial-connections/relink/api/payments-or-payouts.md#relink-specific-account) - [Réassocier tout compte Financial Connections admissible à la même institution](https://docs.stripe.com/financial-connections/relink/api/payments-or-payouts.md#relink-any-eligible-account) ## Savoir quand un compte devient inactif [Côté serveur] Les comptes Financial Connections associés de votre client peuvent devenir inactifs pour plusieurs raisons, notamment : - Le token [OAuth](https://docs.stripe.com/financial-connections/fundamentals.md#how-stripe-links-financial-accounts) fourni à Stripe par sa banque expire au bout d’une certaine période ou pour cause d’inactivité. - Si l’établissement financier modifie ses exigences d’authentification, par exemple en imposant une authentification multifactorielle (MFA), ou si le client change son nom d’utilisateur et son mot de passe. - Si le client révoque l’accès via son portail de services bancaires en ligne. - Si le client clôture son compte auprès de son établissement financier. Nous vous informons lorsqu’un compte Financial Connections devient inactif via le [webhook](https://docs.stripe.com/financial-connections/webhooks.md) `financial_connections.account.deactivated`. Les comptes Financial Connections inactifs incluent des métadonnées supplémentaires sur l’état dans le sous-hachage `status_details.inactive`. Vous ne pouvez pas résoudre toutes les causes d’inactivité d’un compte. Par exemple, vous ne pouvez pas réactiver un compte fermé, sauf si votre client le rouvre. Les comptes que vous ne pouvez pas réparer ont un `status_details.inactive.action` égal à `none`. Vous pouvez [récupérer un compte Financial Connections](https://docs.stripe.com/api/financial_connections/accounts/retrieve.md) à tout moment pour vérifier son état. - La propriété `status_details.inactive.cause` fournit une raison générale expliquant pourquoi un compte Financial Connections est inactif. Par exemple, lorsque la connexion OAuth d’un compte expire, son état est `access_expired`. - La propriété `status_details.inactive.action` indique l’action à effectuer, le cas échéant, pour réactiver le compte. Si votre client peut réactiver le compte en complétant un flux d’authentification de réassociation, son état est `relink_required`. Lorsque `status_details.inactive.action` est `relink_required`, invitez votre client à compléter le flux d’authentification pour réactiver le compte. Par exemple, vous pouvez créer un gestionnaire de webhooks comme celui ci-dessous pour traiter les événements de webhook : #### Python ```python import stripe import requests as r from requests.auth import HTTPBasicAuth # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. client = stripe.StripeClient('<>', stripe_version='2026-04-22.preview') # If you are testing your webhook locally with the Stripe CLI you # can find the endpoint's secret by running `stripe listen` # Otherwise, find your endpoint's secret in your webhook settings in # the Developer Dashboard endpoint_secret = 'whsec_...' @app.route('/webhook', methods=['POST']) def webhook(): event = None payload = request.data sig_header = request.headers["STRIPE_SIGNATURE"] try: event = client.construct_event(payload, sig_header, endpoint_secret) except ValueError as e: # Invalid payload raise e except stripe.error.SignatureVerificationError as e: # Invalid signature raise e if event["type"] == "financial_connections.account.deactivated": account = event["data"]["object"] if account["status"] == "inactive": if "status_details" in account: if account["status_details"]["inactive"]["action"] == "relink_required": prompt_user_to_relink(account) else: # if account does not have "status_details", check that the event destination is configured with the most recent public preview API version else: # No action to be taken. return jsonify(success=True) ``` Le `status` et les `status_details` d’un compte sont également disponibles lorsque vous récupérez un compte Financial Connections. ```curl curl https://api.stripe.com/v1/financial_connections/accounts/{{FINANCIALCONNECTIONSACCOUNT_ID}} \ -u "<>:" \ -H "Stripe-Version: 2026-04-22.preview" ``` ```json { "id": "{{ACCOUNT_ID}}", "object": "financial_connections.account", //..., "authorization": "{{AUTHORIZATION_ID}}", "status": "inactive", "status_details": { "inactive": { "action": "relink_required", "cause": "access_expired" } } } ``` ## Réassociez un compte Financial Connections spécifique [Côté serveur] [Côté client] Créez une session de réassociation en spécifiant `relink_options.authorization` et `relink_options.account`, ce qui oblige votre client à sélectionner le compte Financial Connections identifié par `relink_options.account` lors du flux d’authentification. La session ne réussit avec un compte associé que si votre client réassocie exactement ce compte. Les ressources créées à l’aide du compte Financial Connections existant sont automatiquement mises à jour avec les informations du compte réassocié, y compris les nouveaux numéros de compte tokenisés. Si votre intégration n’exige pas le même compte, vous pouvez permettre à votre client d’[associer un nouveau compte dans la même institution](https://docs.stripe.com/financial-connections/relink/api/payments-or-payouts.md#relink-any-eligible-account). Créez une session Financial Connections et spécifiez les éléments suivants : 1. Définissez `account_holder` sur la même valeur que le champ `account_holder` du compte Financial Connections. Si vous disposez d’un flux de [confirmation en deux étapes](https://docs.stripe.com/payments/build-a-two-step-confirmation.md) ou que vous [collectez les informations de paiement avant de créer un Intent](https://docs.stripe.com/payments/accept-a-payment-deferred.md), le compte Financial Connections n’aura pas de `account_holder`. Dans ce cas, définissez `account_holder` sur `null` lors de la création de la session. 1. Définissez le paramètre de données `permissions` pour inclure `payment_method` et toutes les données que vous souhaitez récupérer sur le compte. Le paramètre `permissions` est un tableau contenant des valeurs, notamment `payment_method`, `balances`, `ownership`, ou `transactions`. Pour protéger la confidentialité des données de votre utilisateur, seules les données de compte que vous avez spécifiées dans le paramètre `permissions` sont accessibles. Définissez les données requises pour répondre à votre cas d’usage et demandez l’autorisation d’accéder uniquement aux données dont vous avez besoin. À l’issue du flux d’authentification, votre utilisateur voit s’afficher les données que vous avez spécifiées à partir du paramètre `permissions`, et consent à partager ces données. L’exemple de code suivant montre comment collecter les valeurs `balances` et `payment_method`. 1. Définissez le paramètre `relink_options.authorization` sur la même valeur que l’ID d’`authorization` du compte Financial Connections. 1. Définissez le paramètre `relink_options.account` sur l’ID du compte Financial Connections. ```curl curl https://api.stripe.com/v1/financial_connections/sessions \ -u "<>:" \ -d "account_holder[type]=customer" \ -d "account_holder[customer]={{CUSTOMER_ID}}" \ -d "permissions[]=payment_method" \ -d "permissions[]=balances" \ -d "relink_options[authorization]={{FINANCIALCONNECTIONSAUTHORIZATION_ID}}" \ -d "relink_options[account]={{FINANCIALCONNECTIONSACCOUNT_ID}}" ``` Cette requête renvoie une réponse semblable à ce qui suit : ``` { "id": "fcsess_abcd", "object": "financial_connections.session", "livemode": true, "account_holder": { "customer": "cus_NfjonN9919dELB", "type": "customer" }, "accounts": [], "client_secret": "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh", "filters": { "account_subcategories": ["checking", "savings"] }, "limits": { "accounts": 1 }, "permissions": ["payment_method", "balances"], "relink_options": { "authorization": "{{AUTHORIZATION_ID}}", "account": "{{ACCOUNT_ID}}" } } ``` 1. Utilisez le `client_secret` renvoyé avec les SDK Stripe côté client pour permettre à votre utilisateur de réassocier ses comptes. Un `client_secret` permet aux SDK Stripe côté client de modifier la session Financial Connections. Ne le stockez pas, ne l’enregistrez pas, ne l’intégrez pas dans des URL et ne le communiquez à personne d’autre que votre client final. Assurez-vous que TLS est activé sur toute page incluant la clé secrète du client. 1. Dans Stripe.js, utilisez [collectFinancialConnectionsAccounts](https://docs.stripe.com/js/financial_connections/collect_financial_connections_accounts) pour collecter un compte. La valeur renvoyée de `collectFinancialConnectionsAccounts` est une Promise. Lorsque l’utilisateur termine le flux d’authentification, la Promise se résout avec un objet qui contient un sous-objet `relink_result`. Si elle aboutit, elle contient également la liste des comptes réassociés. ```js const {financialConnectionsSession, error} = await stripe.collectFinancialConnectionsAccounts({ clientSecret: "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh" }); if (financialConnectionsSession) { if (financialConnectionsSession.relink_result.account) { // relink successful const relinkedAccount = financialConnectionsSession.accounts[0]; } else { switch (financialConnectionsSession.relink_result.failure_reason) { case 'no_account': // user successfully authenticated with their bank, but did not link the expected account break; case 'no_authorization': // user did not successfully authenticate with their bank break; case 'other': // unexpected failure break; } } } ``` Votre client peut s’identifier auprès de son établissement financier avec succès, mais voir une erreur dans le flux d’authentification Financial Connections. Dans ce cas, `relink_result.account` n’est pas défini, car nous ne pouvons pas faire correspondre le compte sélectionné au compte donné dans `relink_options.account`. Dans ce cas, nous suggérons soit de : - Demander à votre client de configurer un nouveau moyen de paiement ou compte bancaire externe. - Demander à votre client de réessayer en utilisant une session Financial Connections qui autorise [tout compte admissible dans la même institution](https://docs.stripe.com/financial-connections/relink/api/payments-or-payouts.md#relink-any-eligible-account). ## Optional: Réassocier tout compte Financial Connections admissible dans la même institution [Côté serveur] [Côté client] Le paramètre `relink_options.account` utilisé dans la section précédente exige que le client associe un compte Financial Connections spécifique. Si le client associe un autre compte, il voit un message d’erreur dans le flux d’authentification. Vous pouvez également créer une session de réassociation en utilisant uniquement `relink_options.authorization`. Cela demande à votre client de s’identifier auprès de la même institution que l’autorisation, sans lui demander de sélectionner un compte particulier. Utilisez `filters.account_subcategories` pour spécifier que votre client ne peut choisir que des comptes chèques ou d’épargne, et utilisez `limits.accounts` pour le limiter à la sélection d’un seul compte. Si votre client sélectionne un compte Financial Connections existant, `status`, `permissions` et `account_numbers` sont mis à jour. Les ressources créées à l’aide du compte Financial Connections existant sont automatiquement mises à jour avec les informations du compte réassocié, y compris les nouveaux numéros de compte tokenisés. Si votre client connecte un nouveau compte, vous pouvez l’utiliser pour créer un moyen de paiement. Les moyens de paiement existants ne sont pas mis à jour automatiquement lorsqu’un nouveau compte est sélectionné dans le flux d’authentification de réassociation. Pour permettre à votre client de connecter un compte Financial Connections éligible aux paiements ou aux virements dans la même institution que son compte inactif, vous devez : 1. Créer une session Financial Connections avec `relink_options.authorization` défini sur l’ID d’autorisation Financial Connections que vous souhaitez réparer, `limits.accounts` défini sur `1` et `filters.account_subcategories` défini sur `["checking", "savings"]` ```curl curl https://api.stripe.com/v1/financial_connections/sessions \ -u "<>:" \ -d "account_holder[type]=customer" \ -d "account_holder[customer]={{CUSTOMER_ID}}" \ -d "filters[account_subcategories][]=checking" \ -d "filters[account_subcategories][]=savings" \ -d "limits[accounts]=1" \ -d "permissions[]=payment_method" \ -d "permissions[]=balances" \ -d "relink_options[authorization]={{FINANCIALCONNECTIONSAUTHORIZATION_ID}}" ``` 1. Utilisez le `client_secret` renvoyé avec les SDK Stripe côté client pour permettre à votre utilisateur de réassocier ses comptes. Un `client_secret` permet aux SDK Stripe côté client de modifier la session Financial Connections. Ne le stockez pas, ne l’enregistrez pas, ne l’intégrez pas dans des URL et ne le communiquez à personne d’autre que votre client final. Assurez-vous que TLS est activé sur toute page incluant la clé secrète du client. 1. Dans Stripe.js, utilisez [collectFinancialConnectionsAccounts](https://docs.stripe.com/js/financial_connections/collect_financial_connections_accounts) pour collecter un compte. La valeur renvoyée de `collectFinancialConnectionsAccounts` est une Promise. Lorsque l’utilisateur termine le flux d’authentification, la Promise se résout avec un objet qui contient un sous-objet `relink_result`. Si elle aboutit, elle contient également la liste des comptes réassociés. 1. Transmettre une liste de comptes associés côté client pour déterminer si le client a associé un nouveau compte dans le flux d’authentification de réassociation. ```js // Fetch existing accounts, or embed them in the server-rendered HTML const existingAccountIds = await fetchExistingAccounts(); const {financialConnectionsSession, error} = await stripe.collectFinancialConnectionsAccounts({ clientSecret: "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh" }); const linkedAccount = financialConnectionsSession?.accounts?.[0] if (linkedAccount) { const isNew = existingAccountIds.includes(linkedAccount.id); } else { // user linked no accounts } ``` Nous vous recommandons d’autoriser un client à associer un nouveau compte pour gérer les cas particuliers suivants lors de la transmission de `relink_options.account` : - Il arrive que Stripe ne reconnaisse aucun des comptes disponibles après que le client se soit authentifié auprès de son institution financière. Dans ce cas, lorsque `relink_options.account` est défini, le flux d’authentification affiche un message d’erreur. Lorsque seul `relink_options.authorization` est défini, le client peut choisir parmi les comptes disponibles et poursuivre le flux de connexion du compte. - Dans les flux OAuth, le client peut sélectionner un compte différent de celui initialement connecté dans la fenêtre modale OAuth de son institution financière. ## Optional: Créez un moyen de paiement [Côté serveur] [Côté client] Les sessions de réassociation qui ne spécifient pas `relink_options.account` peuvent créer de nouveaux comptes Financial Connections. Dans ce cas, les moyens de paiement créés à partir de comptes Financial Connections existants ne seront pas mis à jour. #### Paiements Utilisez un `SetupIntent` pour créer un `PaymentMethod` à l’aide du compte Financial Connections. Définissez la propriété `customer` sur la même valeur que la propriété `account_holder.customer` du compte Financial Connections. Si votre compte Financial Connections n’a pas de valeur `account_holder`, ne définissez pas la propriété `customer`. ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_data[type]=us_bank_account" \ -d "payment_method_data[us_bank_account][financial_connections_account]={{FINANCIALCONNECTIONSACCOUNT_ID}}" \ -d "payment_method_data[billing_details][name]=Jenny Rosen" ``` Cela crée un SetupIntent avec un `status` de `requires_confirmation`. Affichez à votre client un [mandat ACH](https://docs.stripe.com/payments/ach-direct-debit.md#mandates) et utilisez une bibliothèque client Stripe pour [confirmer](https://docs.stripe.com/js/setup_intents/confirm_us_bank_account_setup) le SetupIntent et collecter les données du mandat. ```html
``` En savoir plus sur l’[acceptation des paiements ACH](https://docs.stripe.com/payments/ach-direct-debit.md) #### Virements Utilisez un SetupIntent pour créer et confirmer un PaymentMethod à l’aide du compte Financial Connections. Définissez la propriété `customer` sur la même valeur que la propriété `account_holder.customer` du compte Financial Connections. Si votre compte Financial Connections n’a pas de valeur `account_holder`, ne définissez pas la propriété `customer`. ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "flow_directions[]=outbound" \ -d "payment_method_types[]=us_bank_account" \ -d confirm=true \ -d "payment_method_data[type]=us_bank_account" \ -d "payment_method_data[us_bank_account][financial_connections_account]={{FINANCIALCONNECTIONSACCOUNT_ID}}" \ -d "payment_method_data[billing_details][name]=Jenny Rosen" ``` Créez ensuite un token de compte bancaire en utilisant le `payment_method` associé au SetupIntent. Si vous avez fourni un `customer` lors de la création du SetupIntent, indiquez-le également lors de la création du token. ```curl curl https://api.stripe.com/v1/tokens \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "bank_account[payment_method]={{PAYMENTMETHOD_ID}}" ``` En savoir plus sur les [virements Connect](https://docs.stripe.com/connect/payouts-bank-accounts.md?bank-account-collection-integration=direct-api) ## Optional: Récupérez une autorisation Financial Connections Les comptes Financial Connections possèdent une propriété `authorization` qui correspond à une ressource [Financial Connections authorization](https://docs.stripe.com/api/financial_connections/authorizations/object.md). La ressource d’autorisation décrit l’état global de la connexion de données pour tous les comptes associés à cette autorisation. Lorsque plusieurs comptes font référence à la même autorisation, la réassociation d’un compte peut réactiver d’autres comptes liés à cette autorisation. Cela est normal et n’affecte votre intégration que si vous : 1. Avez un endpoint de webhook qui écoute les événements `financial_connections.account.reactivated`. 1. Disposez d’une logique métier qui suppose qu’une session de réassociation exigeant que l’utilisateur sélectionne un seul compte ne réactivera qu’un seul compte. Récupérez une autorisation pour voir son état : ```curl curl https://api.stripe.com/v1/financial_connections/authorizations/{{FINANCIALCONNECTIONSAUTHORIZATION_ID}} \ -u "<>:" \ -H "Stripe-Version: 2026-04-22.preview" ``` ```json { "id": "{{AUTHORIZATION_ID}}", "object": "financial_connections.authorization", "account_holder": { "customer": "cus_TnvzdXv6VwjyrN", "type": "customer" }, "institution": "fcinst_Qn1a6jqpI0Gb84", "institution_name": "StripeBank", "livemode": false, "status": "active", "status_details": {} } ``` ## Tests Suivez le [guide de test](https://docs.stripe.com/financial-connections/testing.md) pour apprendre à connecter un compte bancaire de test via Financial Connections. Pour tester avec un compte désactivé, recherchez l’institution `Inactive accounts` dans le flux d’authentification et connectez l’un des comptes bancaires fournis. Pour tester le comportement de rafraîchissement des numéros de compte tokenisés, recherchez l’institution `Tokenized Account Numbers` dans le flux d’authentification et connectez l’un des comptes bancaires fournis.