Access ownership details for a Financial Connections accountBeta
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 ownership details are accessible to you 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 wish to access with the data permissions parameter and receive a user’s consent to access this data with the authentication flow.
You’ll generally use the Financial Connections Session to request permission to retrieve ownership details for an account.
If successful, the response returns a Financial Connections Session object:
{ "id": "fcsess_123", "object": "financial_connections.session", "livemode": true, "client_secret": "fcsess_client_secret_wxyz" }
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 will also be null if the ownership permission wasn’t requested or if the account was disconnected.
This is an example of the response after you’ve first collected an account:
{ "id": "fca_abc", "object": "financial_connections.account", "account_holder": { "customer": "cus_abcd", "type": "customer" }, "balance": null, "balance_refresh": null, "category": "cash", "created": 1647973464, "display_name": "Savings", "institution_name": "Stripe 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.
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_abc", "object": "financial_connections.account", "ownership": null, "ownership_refresh": { "status": "pending", "last_attempted_at": {integer timestamp} }, //...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_abc", "object": "financial_connections.account", "ownership": "fcaowns_abcd", "ownership_refresh": { status: "succeeded", last_attempted_at: {integer timestamp} }, // ... }
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_abc", "object": "financial_connections.account", "ownership": { "id": "fcaowns_abcd", "object": "financial_connections.account_ownership", "created": {integer timestamp}, "owners": { "object": "list", "data": [ { "name": "John Smith", "ownership": "fcaowns_abcd", "raw_address": "123 Main St Anytown, NY 10001", "refreshed_at": {integer timestamp} } ], "has_more": false, "url": "/v1/financial_connections/accounts/fca_abc/owners?ownership=fcaowns_abcd" } }, "ownership_refresh": { "status": "succeeded", "last_attempted_at": {integer timestamp} }, // ... }
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_abc", "object": "financial_connections.account", "ownership": { "id": "fcaowns_abcd", // ... }, "ownership_refresh": { "status": "pending", "last_attempted_at": {integer timestamp} }, // ... }
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.
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.