Skip to content
Sign in
An image of the Stripe logo
/
Create account
Sign in
Home
Payments
Finance automation
Banking as a service
Developer tools
No-code
All products
Home
Payments
Finance automation
Home
Payments
Finance automation
Banking as a service
Developer tools
Overview
Get started
About Stripe payments
Start an integration
Payment Links
Checkout
Web Elements
Mobile Elements
Payment scenarios
During the payment
After the payment
Add payment methods
More payment scenarios
Faster checkout with Link
Other Stripe products
Connect
Terminal
Radar
Financial Connections
    Overview
    Getting Started
    Fundamentals
    Use cases
    Testing
    Collect accounts for data
    ACH Direct Debit payments
    Connect payouts
    Other data-powered products
    Access account data
    Balances
    Ownership
    Transactions
    Manage accounts
    Disconnections
    Webhooks
Crypto
Identity
Climate
Resources
About the APIs
Implementation guides
Regulation support
Testing
Financial Connections
·
HomePaymentsFinancial Connections

Access ownership details for a Financial Connections account
Beta

Learn how to access an account’s ownership details with your user’s permission.

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

Command Line
curl https://api.stripe.com/v1/financial_connections/sessions \ -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:"
\ -d "account_holder[type]"=customer \ -d "account_holder[customer]"=
{{CUSTOMER_ID}}
\ -d "permissions[]"=ownership \ -d "prefetch[]"=ownership

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 details
Server-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:

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

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:

Command Line
curl https://api.stripe.com/v1/financial_connections/accounts/
{{ACCOUNT_ID}}
\ -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:"

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:

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

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:

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

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.

OptionalRequest an account’s ownership details when adding an account to accept an ACH Direct Debit payment
Server-side

Was this page helpful?
Need help? Contact Support.
Watch our developer tutorials.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Request an account’s ownership details
Retrieve an account’s ownership details
Refresh an account’s ownership details
Failure to retrieve ownership details on an account
Products Used
Financial Connections
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g., )
The Stripe Shell is best experienced on desktop.
$