# Accéder aux soldes d'un compte Financial Connections Découvrez comment accéder aux soldes d'un compte avec l'autorisation de votre utilisateur. L’API Financial Connections vous permet de récupérer les soldes actualisés d’un [compte Financial Connections](https://docs.stripe.com/api/financial_connections/accounts.md). Les données de solde peuvent être utiles à de nombreuses applications, notamment pour réduire le risque d’échec de paiements ACH liés à des fonds insuffisants, l’évaluation des risques ou la création d’outils de gestion financière. ## Before you begin Vous devez disposer d’une inscription Financial Connections pour accéder à balances en mode production. Accédez aux [paramètres de votre Dashboard](https://dashboard.stripe.com/settings/financial-connections) pour vérifier l’état de votre inscription ou entamer le processus d’inscription. Les données de test Financial Connections sont disponibles en permanence. ## Créer un client [Recommended] [Server-side] Nous vous recommandons de créer un objet Customer ** (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) contenant une adresse e-mail, qui représentera votre utilisateur et que vous pourrez ensuite associer à votre paiement. L’association d’un objet `Customer` vous permettra par la suite de [répertorier les comptes précédemment associés](https://docs.stripe.com/api/financial_connections/accounts/list.md). En renseignant une adresse e-mail et un numéro de téléphone dans l’objet `Customer`, vous permettez à Financial Connections d’améliorer le flux d’authentification en simplifiant l’inscription ou la connexion de votre utilisateur, selon qu’il s’agit d’un nouvel utilisateur de [Link](https://support.stripe.com/questions/link-for-financial-connections-support-for-businesses). ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d email={{CUSTOMER_EMAIL}} \ -d phone={{CUSTOMER_PHONE}} ``` ## Demander l'accès aux soldes d'un compte [Côté serveur] Vous devez d’abord collecter un compte avant de pouvoir accéder aux données de son solde. Pour découvrir comment collecter les informations d’un compte Financial Connections, consultez le guide d’intégration correspondant le mieux à votre cas d’usage : [accepter des paiements](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md), [faciliter des virements Connect](https://docs.stripe.com/financial-connections/connect-payouts.md) ou [créer d’autres produits reposant sur les données](https://docs.stripe.com/financial-connections/other-data-powered-products.md). Lorsque vous collectez les données d’un compte, vous devez spécifier les données auxquelles vous avez besoin d’accéder à l’aide du paramètre [autorisations](https://docs.stripe.com/financial-connections/fundamentals.md#data-permissions). L’utilisateur peut consulter l’ensemble des autorisations d’accès aux données demandées dans le [flux d’authentification](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow). Les comptes Financial Connections peuvent être collectés via différents chemins d’intégration, et la façon de spécifier le paramètre varie légèrement en fonction de l’API. #### Payment Intents ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=20000 \ -d currency=usd \ -d customer="{{CUSTOMER_ID}}" \ -d "payment_method_types[]"=us_bank_account \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=balances \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=payment_method ``` #### Setup Intents ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d "payment_method_types[]"=us_bank_account \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=balances \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=payment_method ``` #### Sessions ```curl curl https://api.stripe.com/v1/financial_connections/sessions \ -u "<>:" \ -d "account_holder[type]"=customer \ -d "account_holder[customer]"="{{CUSTOMER_ID}}" \ -d "permissions[]"=balances ``` #### Payer ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d "payment_method_types[]"=us_bank_account \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=balances \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=payment_method ``` #### Factures ```curl curl https://api.stripe.com/v1/invoices \ -u "<>:" \ -d customer="{{CUSTOMER_ID}}" \ -d "payment_settings[payment_method_types][]"=us_bank_account \ -d "payment_settings[payment_method_options][us_bank_account][financial_connections][permissions][]"=balances \ -d "payment_settings[payment_method_options][us_bank_account][financial_connections][permissions][]"=payment_method ``` #### Abonnements ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d customer={{CUSTOMER_ID}} \ -d "payment_settings[payment_method_types][]"=us_bank_account \ -d "payment_settings[payment_method_options][us_bank_account][financial_connections][permissions][]"=balances \ -d "payment_settings[payment_method_options][us_bank_account][financial_connections][permissions][]"=payment_method ``` Si vous utilisez des moyens de paiement dynamiques pour certaines API de paiement, vous pouvez également configurer les autorisations demandées dans le Dashboard. Découvrez comment [accéder aux données supplémentaires sur les comptes Financial Connections](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md?dashboard-or-api=dashboard#access). ## Initier une actualisation du solde [Côté serveur] Toutes les récupérations de données Financial Connections sont asynchrones. Vous devez lancer une actualisation du solde et attendre qu’elle se termine, puis récupérer les résultats. Vous pouvez initier des actualisations de solde via le paramètre API `prefetch` ou l’[API Refresh](https://docs.stripe.com/api/financial_connections/accounts/refresh.md). ### Récupérer les données de solde Précisez si vous souhaitez récupérer les soldes du compte *avant* la collecte du compte. Le processus d’actualisation est alors lancé dès que votre utilisateur se connecte à on compte dans le [flux d’authentification](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow). Configurez le paramètre `prefetch` lorsque vous avez besoin des données de solde de chaque compte associé pour vous assurer de les recevoir au plus vite. C’est le cas, par exemple, lorsque vous prévoyez d’effectuer des contrôles de solde avant d’initier un paiement ACH. Le paramètre `prefetch` est disponible sur toutes les API qui prennent en charge Financial Connections. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=20000 \ -d currency=usd \ -d "payment_method_types[]"=us_bank_account \ -d "payment_method_options[us_bank_account][financial_connections][prefetch][]"=balances \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=payment_method \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=balances ``` ### Lancer une actualisation à la demande Utilisez [l’API Refresh](https://docs.stripe.com/api/financial_connections/accounts/refresh.md) pour lancer des actualisations de solde à la demande *après* l’encaissement du compte, et récupérer des informations sur le solde d’un compte en particulier à votre convenance, ce qui vous permet de reporter la décision à un moment ultérieur. Utilisez l’ID du compte Financial Connections pour lancer une actualisation. Si vous effectuez l’intégration via un tunnel de paiement, recherchez l’ID du compte [sur le moyen de paiement associé](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md#finding-the-financial-connections-account-id). Lorsque vous utilisez une session Financial Connections, récupérez-la [via la session](https://docs.stripe.com/financial-connections/other-data-powered-products.md?platform=web#collect-an-account). ```curl curl https://api.stripe.com/v1/financial_connections/accounts/{{FINANCIALCONNECTIONSACCOUNT_ID}}/refresh \ -u "<>:" \ -d "features[]"=balance ``` > Les actualisations ne sont pas autorisées sur les comptes inactifs. ### Attendre la fin de l’actualisation des soldes Le champ [balance_refresh](https://docs.stripe.com/api/financial_connections/accounts/object.md#financial_connections_account_object-balance_refresh) d’un compte Financial Connections représente l’état d’actualisation du solde. Ce champ reste `null` jusqu’à ce que vous demandiez l’autorisation `balances` et initiez une actualisation. Une fois que vous avez lancé une actualisation du solde, l’état passe à `pending`. Une fois terminée, il bascule sur `succeeded` ou `failed`. Nous envoyons l’événement [financial_connections.account.refreshed_balance](https://docs.stripe.com/api/events/types.md#event_types-financial_connections.account.refreshed_balance) lorsque l’actualisation du solde a été effectuée. Pour déterminer si l’actualisation a abouti, vérifiez le champ `balance_refresh.status` lors du traitement du webhook. Flux d'actualisation du solde (See full diagram at https://docs.stripe.com/financial-connections/balances) Une fois le solde actualisé, Stripe définit la disponibilité des actualisations futures via le champ [balance_refresh.next_refresh_available_at](https://docs.stripe.com/api/financial_connections/accounts/object.md#financial_connections_account_object-balance_refresh-next_refresh_available_at). Vérifiez ce champ avant d’initier une nouvelle actualisation de solde pour vous assurer que des actualisations sont effectivement disponibles actuellement. Si vous tentez une actualisation alors que la valeur est `null` (comme c’est toujours le cas lorsque l’actualisation est en attente ou que le compte est inactif) ou que l’heure actuelle est inférieure à l’horodatage `next_refresh_available_at`, l’actualisation ne sera pas initiée. > Dans le cas improbable où une actualisation échoue, le champ `error` sur le hachage d’actualisation est une fonctionnalité bêta qui renseigne sur la cause de l’échec et indique les étapes suivantes recommandées. Si vous souhaitez l’utiliser, contactez-nous par [e-mail](mailto:financial-connections-beta+refresh-error@stripe.com) pour obtenir votre accès. ## Récupérer les soldes d'un compte [Côté serveur] Une fois l’actualisation du solde terminée, récupérez le compte Financial Connections dans le corps de l’événement [financial_connections.account.refreshed_balance](https://docs.stripe.com/api/events/types.md#event_types-financial_connections.account.refreshed_balance) ou via l’API. ```curl curl https://api.stripe.com/v1/financial_connections/accounts/{{FINANCIALCONNECTIONSACCOUNT_ID}} \ -u "<>:" ``` Si l’actualisation a abouti, l’objet Account contient les données de solde. ```json { "id": "fca_1Jbry3BAjqvGMUSxCDjFsrLU", "object": "financial_connections.account", "balance": { "as_of": 1651516592, "cash": { "available": { "usd": 6000 } }, "current": { "usd": 6000 }, "type": "cash" }, "balance_refresh": { "last_attempted_at": 1651516582, "next_refresh_available_at": 1651516583, "status": "succeeded", }, // ... other fields on the Financial Connections Account } ``` #### Détails des données de solde Le hachage `balance` décrit les différents types de soldes communiqués par un établissement financier. | Types de solde | Description | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `current` | Le solde `current` désigne le montant des fonds comptabilisés sur le compte. Ce montant ne prend donc pas en compte les événements qui n’ont pas encore été comptabilisés sur un compte, tels que les transferts entrants, les transferts sortants et d’autres fonds. Un montant positif indique les fonds dus au titulaire de compte. À l’inverse, un montant négatif indique les fonds dus par le titulaire de compte. | | `available` | L’objet balance peut se présenter sous deux formes `cash` et `credit`. Si le solde possède la valeur `type: "cash"`, un sous-objet `cash` avec la propriété `available` apparaît. Il correspond au montant des fonds disponibles, tels que les montants à transférer ou versés, après que les fonds entrants et sortants ont été pris en compte. | | `used` | L’objet Balance est polymorphe ; il peut prendre les types `cash` et `credit`. S’il contient `type: "credit"`, il contiendra également un sous-objet `credit` avec la propriété `used`, qui correspond au montant des fonds utilisés après la prise en compte des fonds sortants bloqués. Les montants `current` et `used` des soldes créditeurs suivent les mêmes conventions de signes que les soldes disponibles. Autrement dit, un montant positif désigne des fonds dus *au* titulaire du compte. À l’inverse, un montant négatif désigne des fonds dus *par* le titulaire du compte. Dans la plupart des cas, un solde créditeur affiche des montants négatifs. | La disponibilité des soldes varie selon l’établissement financier sous-jacent. Nous renvoyons toutes les données de solde auxquelles nous avons accès. Dans de rares cas, le plus souvent lorsqu’il s’agit de petits établissements financiers, Stripe ne peut pas récupérer les données de solde auprès d’un établissement financier ou d’un partenaire, auquel cas l’objet `solde` est `null`. L’objet solde est également `null` si le compte a été déconnecté. Dans certains cas, seul le solde `current` est renvoyé, ou un solde datant de moins de 24 heures. Consultez notre liste des [établissements pris en charge](https://docs.stripe.com/financial-connections/supported-institutions.md) pour connaître la couverture des données. Pour le type de solde `cash`, utilisez le sous-objet `available` pour confirmer que les fonds existants sont suffisants avant d’initier un paiement par prélèvement automatique ACH. Si un solde `available` est nul, vous pouvez utiliser le solde `current` à la place. Veuillez toutefois garder à l’esprit que ce montant ignore les événements qui n’ont pas encore été comptabilisés sur un compte, tels que les transferts entrants, les transferts sortants et les autres fonds bloqués. Le champ `as_of` d’un solde correspond à la date et à l’heure auxquelles l’établissement financier a calculé ce solde. Il ne s’agit pas de la date et de l’heure auxquelles les données de solde ont été récupérées. Par exemple, certains établissements financiers ne mettent à jour les données du solde qu’une fois par jour, tandis que d’autres les mettent à jour plus fréquemment.