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. 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.

Avant de commencer

Vous devez disposer d’une inscription à Financial Connections pour accéder aux balances en mode production. Consultez les Paramètres du Dashboard pour connaître l’état de votre inscription ou lancer le processus d’inscription. Les données Financial Connections en mode test sont toujours disponibles.

Créer un client
Recommended
Server-side

Nous vous recommandons de créer un objet Customer 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. En renseignant une adresse e-mail 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 ou d’un utilisateur existant.

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, faciliter des virements Connect ou créer d’autres produits reposant sur les données.

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. L’utilisateur peut consulter l’ensemble des autorisations d’accès aux données demandées dans le flux d’authentification. 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.

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.

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.

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. 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.

Lancer une actualisation à la demande

Utilisez l’API Refresh 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é. Lorsque vous utilisez une session Financial Connections, récupérez-la via la session.

Note

Les actualisations ne sont pas autorisées sur les comptes inactifs.

Attendre la fin de l’actualisation des soldes

Le champ 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 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.

Une fois le solde actualisé, Stripe définit la disponibilité des actualisations futures via le champ 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.

Bêta

Dans le cas improbable où une actualisation échoue, le champ error sur le hachage d’actualisation est une fonctionnalité bêta qui fournit la cause de l’échec et les étapes suivantes recommandées. Si vous souhaitez utiliser cette fonctionnalité, envoyez-nous un e-mail pour y accéder.

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 ou via l’API.

Si l’actualisation a abouti, l’objet Account contient les données de solde.

{
  "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 tous les soldes disponibles auxquels nous avons accès. Dans de rares cas, le plus souvent lorsqu’il s’agit d’établissements financiers de petite taille, Stripe n’est pas en mesure de récupérer les données de solde : à ce moment-là, la valeur de l’objet balance est null. L’objet Balance présente également la valeur null si le compte a été déconnecté. Dans certains cas, seul un solde current est renvoyé. Consultez notre liste des établissements pris en charge pour en savoir plus sur 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.