Accéder aux informations relatives au titulaire d'un compte Financial Connections

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.

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d email={{CUSTOMER_EMAIL}}

Vous devez d’abord collecter les informations d’un compte avant de pouvoir accéder aux données de propriété. 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 (par exemple, accepter des paiements, faciliter des virements Connect ou créer d’autres produits reposant sur les données).

Si vous utilisez le flux d’inscription Connect Onboarding pour les comptes Custom afin de collecter des informations sur les comptes Financial Connections, configurez les données auxquelles vous souhaitez accéder dans le Dashboard.

Si vous utilisez une intégration de l’API pour collecter les informations des comptes, spécifiez les données auxquelles vous avez besoin d’accéder à l’aide du paramètre permissions. 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.

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "payment_method_types[]"=us_bank_account \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=ownership \
  -d "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.

Toutes les récupérations de données Financial Connections sont asynchrones. Vous devez lancer une actualisation de la propriété et attendre qu’elle se termine, puis récupérer les résultats. Vous pouvez initier des actualisations de la propriété de deux manières via le paramètre prefetch de l’API ou l’API Refresh.

Récupérer les données de propriété de manière anticipée

Précisez si vous souhaitez récupérer les informations de propriété du compte avant la collecte du compte. Le processus d’actualisation est alors lancé dès que votre utilisateur connecte son compte dans le flux d’authentification. Configurez le paramètre prefetch lorsque vous avez besoin des données de propriété de chaque compte associé pour vous assurer de les recevoir au plus vite. Le paramètre prefetch est disponible sur toutes les API qui prennent en charge Financial Connections.

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "payment_method_types[]"=us_bank_account \
  -d "payment_method_options[us_bank_account][financial_connections][prefetch][]"=ownership \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=payment_method \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=ownership

Lancer une actualisation à la demande

Utilisez l’API Refresh pour lancer des actualisations de la propriété à la demande après la collecte du compte et récupérer les informations de propriété d’un compte spécifique. Vous pourrez ainsi reporter la décision à une date ultérieure. Bien que les données de propriété d’un compte puissent changer, elles ne changent généralement pas aussi fréquemment que les données de solde ou de transaction.

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.

curl https://api.stripe.com/v1/financial_connections/accounts/
{{ACCOUNT_ID}}
/refresh \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "features[]"=ownership

Attendre la fin de l’actualisation de la propriété

Le champ ownership_refresh d’un compte Financial Connections représente l’état d’actualisation de la propriété. Ce champ reste null jusqu’à ce que vous demandiez l’autorisation ownership et initiez une actualisation. Une fois que vous avez lancé une actualisation de la propriété, l’état passe à pending. Une fois terminée, il bascule sur succeeded ou failed. Nous envoyons l’événement financial_connections.account.refreshed_ownership lorsque l’actualisation de la propriété a été effectuée. Pour déterminer si l’actualisation de la propriété a abouti, vérifiez le champ ownership_refresh.status lors du traitement du webhook.

Une fois les propriétés actualisées, Stripe définit la disponibilité des actualisations futures via le champ ownership_refresh.next_refresh_available_at. Vérifiez ce champ avant d’initier une nouvelle actualisation des propriétés 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.

Une fois l’actualisation de la propriété terminée, récupérez le compte Financial Connections depuis l’API et développez le champ de ownership pour afficher les informations relatives aux propriétaires.

curl -G https://api.stripe.com/v1/financial_connections/accounts/
{{ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "expand[]"=ownership

Cette opération renvoie le compte Financial Connections avec le champ relatif à la propriété développé de manière à répertorier les propriétaires du compte :

{
  "id": "fca_zbyrdjTrwcYZJZc6WBs6GPid",
  "object": "financial_connections.account",
  "ownership": {
    "id": "fcaowns_1MzTG4IG1CZuezXppfPbUpXb",
    "object": "financial_connections.account_ownership",
    "created": 1651784999,
    "owners": {
      "object": "list",
      "data": [
        {
          "name": "Jenny Rosen",
          "email": "jenny.rosen@example.com",
          "phone": "+1 555-555-5555",
          "ownership": "fcaowns_1MzTG4IG1CZuezXppfPbUpXb",
          "raw_address": "510 Townsend San Francisco, CA 94103",
          "refreshed_at": 1651784999
        }
      ],
      "has_more": false,
      "url": "/v1/financial_connections/accounts/fca_zbyrdjTrwcYZJZc6WBs6GPid/owners?ownership=fcaowns_1MzTG4IG1CZuezXppfPbUpXb"
    }
  },
  "ownership_refresh": {
    "status": "succeeded",
    "last_attempted_at": 1651784999,
    "next_refresh_available_at": 1651785000
  },
  // ...
}

Stripe renvoie les informations de propriété communiquées par un établissement financier, mais la disponibilité de ces renseignements varie. Nous renvoyons tous les champs et titulaires fournis par la banque. Les informations relatives au titulaire du compte peuvent comporter ses nom, adresse, adresse e-mail et numéro de téléphone.