Access ownership details for a Financial Connections accountBeta
Note
Access to ownership details is available as part of a US private beta. You can get started immediately with test-mode and request access to live-mode.
The Financial Connections API allows you to request, retrieve, and refresh the ownership details of a Financial Connections Account.
Request an account’s ownership detailsServer-side
You must collect an account before you can access ownership details in the Financial Connections API. To learn more about how to collect a Financial Connections account, consult the integration guide most relevant to your use case: accept payments, facilitate Connect payouts or build other-data powered products.
When collecting an account, you must specify the data you need to access with the data permissions parameter and receive a user’s consent to access it with the authentication flow.
We recommend using a Financial Connections Session to request permission to retrieve ownership details for an account.
Optionally, you can request to prefetch ownership, which retrieves ownership on account creation. The prefetch parameter saves you from making another API call to retrieve data after account creation and reduces the latency of data retrieval.
If successful, the response returns a Financial Connections Session object:
{ "id": "fcsess_1MuOL4IG1CZuezXpoeuzQJYm", "object": "financial_connections.session", "livemode": true, "client_secret": "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh" }
Retrieve an account’s ownership detailsServer-side
When you collect an account for the first time, the account will have null ownership details.
This field is also null if you didn’t request the ownership permission or if the account was disconnected.
This is an example of the response after you’ve first collected an account:
{ "id": "fca_zbyrdjTrwcYZJZc6WBs6GPid", "object": "financial_connections.account", "account_holder": { "customer": "cus_NfjonN9919dELB", "type": "customer" }, "balance": null, "balance_refresh": null, "category": "cash", "created": 1647973464, "display_name": "Savings", "institution_name": "Test Bank", "last4": "2222", "livemode": true, "ownership": null, "ownership_refresh": null, "permissions": [ "ownership" ], "status": "active", "subcategory": "savings", "supported_payment_method_types": [ "us_bank_account" ] }
The ownership_refresh hash describes the most recent refresh of ownership details. If you opted to prefetch ownership, an asynchronous refresh starts during account creation, and you won’t need to make a refresh call until you need updated data.
Request an asynchronous refresh to retrieve updated ownership details with the Financial Connections account refresh action:
This causes Stripe to retrieve the latest ownership details available from the financial institution.
The request returns the account, but doesn’t reflect the updated ownership details.
The response describes the current state of the Financial Connections account. In particular, ownership_refresh.status is now pending:
{ "id": "fca_zbyrdjTrwcYZJZc6WBs6GPid", "object": "financial_connections.account", "ownership": null, "ownership_refresh": { "status": "pending", "last_attempted_at": 1651784999, "next_refresh_available_at": null }, //...rest of FinancialConnectionsAccount resource }
In the background, Stripe attempts to retrieve account ownership details for this account.
After a few seconds, retrieve the Financial Connections account again:
If the background process succeeds, the Financial Connections account resource shows the ownership_refresh.status as succeeded, and has a value for ownership:
{ "id": "fca_zbyrdjTrwcYZJZc6WBs6GPid", "object": "financial_connections.account", "ownership": "fcaowns_1MzTG4IG1CZuezXppfPbUpXb", "ownership_refresh": { status: "succeeded", "last_attempted_at": 1651784999, "next_refresh_available_at": 1651785000 }, // ... }
The time required to fetch the most recent ownership details can vary depending on the financial institution, but is generally returned in less than 10 seconds.
Depending on your use case, you may want to retrieve ownership details periodically. Account details can change. For example, an account holder’s address changes in the event of a relocation.
The ownership field can be expanded when retrieving a Financial Connections account:
The response contains the Financial Connections account as before, but with the ownership field expanded to list the account’s owners:
{ "id": "fca_zbyrdjTrwcYZJZc6WBs6GPid", "object": "financial_connections.account", "ownership": { "id": "fcaowns_1MzTG4IG1CZuezXppfPbUpXb", "object": "financial_connections.account_ownership", "created": 1651784999, "owners": { "object": "list", "data": [ { "name": "John Smith", "ownership": "fcaowns_1MzTG4IG1CZuezXppfPbUpXb", "raw_address": "123 Main St Anytown, NY 10001", "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 returns the ownership information made available by a financial institution, and the availability of ownership details varies. We return all available fields and owners provided by the bank. Ownership details can include account owner name, address, email, and phone number.
After the refresh completes, Stripe emits a financial_connections.account.refreshed_ownership webhook. The webhook includes the Financial Connections account object with the latest ownership details.
Use the retrieve Financial Connections Account API to retrieve and expand the ownership attribute.
Refresh an account’s ownership details
Account ownership details don’t change often, but it might change over time. For example, the account owner may change their residence, their name, or add a joint owner to the account.
To get the most up-to-date account ownership details, make another request to the account refresh endpoint:
As before, the response shows the current state of the Financial Connections account:
{ "id": "fca_zbyrdjTrwcYZJZc6WBs6GPid", "object": "financial_connections.account", "ownership": { "id": "fcaowns_1MzTG4IG1CZuezXppfPbUpXb", // ... }, "ownership_refresh": { "status": "pending", "last_attempted_at": 1651784999, "next_refresh_available_at": null }, // ... }
This again causes Stripe to retrieve the latest ownership details from the financial institution.
After the refresh completes, Stripe emits a financial_connections.account.refreshed_balance webhook.
The webhook includes the Financial Connections account object with the latest ownership details.
A successful refresh doesn’t necessarily mean the ownership details changed.
After the completion of a ownership refresh, Stripe sets the availability of ownership refreshes through the next_refresh_available_at timestamp field.
Check the next_refresh_available_at field on the ownership_refresh hash before initiating a subsequent ownership refresh to make sure that ownership refreshes are currently available. If you attempt a refresh while the value is null (as is always the case when the refresh is pending) or the current time is less than the next_refresh_available_at timestamp, the refresh won’t be initiated.
Failure to retrieve ownership details on an account
Retrieving ownership details requires communicating with a financial institution. This communication can occasionally fail.
If we can’t retrieve owners details, the ownership_refresh.status will be failed, and you receive a financial_connections.account.refreshed_ownership webhook with the updated Financial Connections account resource. However, the account ownership details from the previous successful refresh are available when you retrieve the Financial Connections account and pass the expand[]=ownership query parameter.