ユーザーの許可を得て Financial Connections アカウントへのデータアクセスをの関連付けを変更する公開プレビュー
ユーザーの許可を得て非アクティブな口座でデータアクセスを再確立する方法をご紹介します。
以下のようにさまざまな理由で、エンドユーザーにすでに関連付けられていた Financial Connections アカウントが inactive になることがあります。
- 金融機関から Stripe に提供された OAuth トークンは、一定期間の経過後、または操作が行われていないことを理由として有効期限が切れます。
- 金融機関が多要素認証の要件を変更した。
- 不審なアクティビティーが原因で口座が金融機関によってロックされる。
- ユーザーが金融機関の口座を解約する。
- ユーザーがユーザー名またはパスワードを変更した。
- ユーザーが、お客様または Stripe とデータ共有のアクセス権を取り消す。
非アクティブなアカウントでは、新しい口座データにアクセスできません。稀に、新しい口座データに永続的にアクセスできなくなることがあります。たとえば、エンドユーザーが金融機関の口座を解約した場合です。その他すべてのケースでは、ユーザーは、再認証を行って、新しい口座データの共有に同意する必要があります。
Financial Connections API では、以前に関連付けられていた口座の金融機関にユーザーを直接移動する、効率的な認証フローを使用して、(ユーザーの許可を得た上で) 以前に関連付けられていた Financial Connections アカウントのデータ接続を修復できます。
ユーザーがいつアカウントを再リンクするべきかを把握するには、以下のコードスニペットにあるように、すべてのリクエストや Webhook エンドポイント内において 2026-01-28.などのプレビュー版 API バージョンを使用する必要があります。
口座が非アクティブになる時点を把握するサーバー側
以前に関連付けられていた Financial Connections アカウントが 非アクティブになった場合は、financial_ Webhook で通知されます。口座の承認が inactive である場合、inactive の承認を再度関連付けることが可能であれば、Authorization オブジェクトの status_ ハッシュの inactive サブハッシュに、relink_ アクションが示されます。たとえば、以下のような Webhook ハンドラーを設定して Webhook イベントを処理することが必要になる場合があります。
さらに、口座 ID を使用して口座を取得することで、口座のステータスを取得することができます。
curl https://api.stripe.com/v1/financial_connections/accounts/:id \ -u: \ -X "GET" \ -H "Stripe-Version: 2026-01-28.preview"sk_test_BQokikJOvBiI2HlWgH4olfQ2
{ "id": "fca_1LDYuMGxLVUXRs6HW0lrat9T", "object": "financial_connections.account", //..., "authorization": "fcauth_1LDYuMGxLVUXRs6HW0lrat9T", "status": "inactive" }
その後、承認 ID を使用して口座の承認を取得することができます。
curl https://api.stripe.com/v1/financial_connections/authorizations/:id \ -u: \ -X "GET" \ -H "Stripe-Version: 2026-01-28.preview"sk_test_BQokikJOvBiI2HlWgH4olfQ2
{ "id": "fcauth_1LDYuMGxLVUXRs6HW0lrat9T", "object": "financial_connections.authorization", //..., "status": "inactive", "status_details": { "inactive": { "action": "relink_required" } } }
非アクティブな口座を関連付けなおしてデータにアクセスすることができない場合、authorization. は none です。このような場合は、エンドユーザーを通常の認証フローにリダイレクトして、金融機関を選択し、口座を最初から関連付けます。
{ "id": "fcauth_1LDYuMGxLVUXRs6HW0lrat9T", "object": "financial_connections.authorization", //..., "status": "inactive", "status_details": { "inactive": { "action": "none" } } }
口座の承認がアクティブであっても、口座自体が非アクティブである場合があります。この状況は、たとえば、金融機関で口座が解約されている場合に起こることがあります。このような場合、非アクティブな口座を関連付けなおしてデータにアクセスすることはできません。この場合も同様に、エンドユーザーを通常の認証フローにリダイレクトして、金融機関を選択し、口座を最初から関連付けます。
非アクティブな Financial Connections アカウントから関連付けを変更するための承認を取得するサーバー側
非アクティブなアカウントのデータアクセスを再確立するには、アカウントオブジェクトからアカウントの承認の ID を取得します。
{ "id": "fca_1LDYuMGxLVUXRs6HW0lrat9T", "object": "financial_connections.account", //..., "authorization": "fcauth_1LDYuMGxLVUXRs6HW0lrat9T", "status": "inactive" }
Financial Connections アカウントでデータアクセスを修復する際は 2 つのオプションがあります。これは、Stripe で ACH ダイレクトデビットの決済を受け付けるために関連付けられていた口座の修復が目的であるか、その他の目的であるかよって決まります。
Financial Connections を使用するユーザーの銀行口座からデータアクセスを復元するには、ユーザーが、認証フローを使用して口座を再認証する必要があります。ユーザーは、口座をサイトやアプリケーションに関連付けなおす必要がある場合に認証フローを開始します。サイトやアプリケーションにユーザーが口座を関連付けなおすためのボタンやリンクを挿入してください。たとえば、「Re-link your bank account (銀行口座を再度関連付ける)」というボタンにすることができます。
認証フローが表示されると、エンドユーザーは関連金融機関で口座へのアクセスを認証するように求められます。ユーザーが最初に新しい口座を関連付ける場合の認証フローとは異なり、エンドユーザーは、銀行選択機能から金融機関を選択する必要はありません。
オプションACH ダイレクトデビットによる決済を受け付けるために Financial Connections アカウントのデータアクセスを修復する
Financial Connections セッションを作成する
Financial Connections Session を作成し、以下を指定します。
account_を顧客のholder[customer] idに設定します。- データの
permissionsパラメーターを設定してpayment_を組み込み、口座について取得するデータを設定します。permissions パラメーターは、method [payment_などの値が含まれる配列です。ユーザーのデータのプライバシーを保護するために、アクセスできる口座データはmethod, balances, ownership, transactions] permissionsパラメーターで指定したデータに制限されます。ユースケースに対応するために必要なデータを慎重に検討して、必要なデータのみにアクセスするための権限をリクエストします。認証フローが完了すると、permissions パラメーターで指定されたデータがユーザーに表示され、ユーザーはこのデータを共有するための同意を提供します。以下のコード例は、balancesとpayment_を収集する方法を示しています。method relink_を承認 ID に設定して、データアクセスを修復する口座の承認を指定します。options[authorization] filters[account_をsubcategories] checking、savingsに設定します。limits[accounts]を1に設定します。
Stripe で ACH ダイレクトデビットによる決済を受け付けるために追加できる引き落とし可能な口座は 1 つのみです。
このリクエストでは、次のようなレスポンスが返されます。
{ "id": "fcsess_abcd", "object": "financial_connections.session", "livemode": true, "account_holder": { "customer": "cus_NfjonN9919dELB", "type": "customer" }, "accounts": [], "client_secret": "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh", "filters": { "account_subcategories": ["checking", "savings"] }, "limits": { "accounts": 1 }, "permissions": [ "payment_method", "balances" ], "relink_options": { "authorization": "fcauth_1LDYuMGxLVUXRs6HW0lrat9T" } }
Financial Connections アカウントを再度関連付ける
返された client_ を Stripe.js で使用して、ユーザーが口座の関連付けを変更できるようにします。client_ により、クライアント側の Stripe SDK は Financial Connections Session を変更できます。これは、保存したり、ログに記録したり、URL に埋め込んだり、当該エンドユーザー以外の人に公開したりしないでください。client secret が含まれるすべてのページで TLS を有効化するのを忘れないでください。
口座を収集するには、stripe. を使用します。
// Fetch existing accounts on the authorization to determine whether the linked account is new. const existing_account_ids = await fetch_existing_accounts(); const financialConnectionsSessionResult = await stripe.collectFinancialConnectionsAccounts({ clientSecret: "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh" });
Stripe.js が認証フローを読み込みます。クライアント側の Stripe.js UI によってユーザーは、貴社が permissions パラメーターを使用してアクセスをリクエストしたデータを確認して共有に同意することと、金融口座を貴社と Stripe に関連付けなおすことができます。
認証フローは以下のようになります。

stripe. の戻り値は Promise です。ユーザーが認証フローを完了すると、Promise は、関連付けの変更後の口座のリストを含むオブジェクトで解決されます。
stripe.collectFinancialConnectionsAccounts(clientSecret) .then(({financialConnectionsSession, error}) => { if (error) { // The session failed for some reason. console.error(error.message); } else if (financialConnectionsSession.accounts.length > 0) { // User has authorized some account on the authorization. const is_new = !existing_account_ids.includes(financialConnectionsSession.accounts[0].id); // The user has connected a new account on the authorization. if (is_new) { // You must surface the mandate for new accounts to process ACH payments. return surface_mandate(); } else { // User has reauthorized an existing payment account. reload_account(financialConnectionsSession.accounts[0].id); return display_success(); } } else if (accounts.length == 0) { // The session failed to connect an account. } });
ユーザーがデータ共有する口座を関連付けている場合、accounts の長さは > 0 です。
エンドユーザーの金融機関の OAuth フロー内で、ユーザーは最初に関連付けたものとは別の口座を選択することができます。ユーザーが最初に関連付けた口座とは別の口座を関連付けた場合、is_ フィールドに新しい口座 ID が示されます。支払い方法への新しく作成した Financial Connections アカウントの変換のステップに従ってください。
ユーザーに引き落とし可能な口座がない場合、accounts の長さは 0 です。
トークン化された口座番号を持つデビット口座の再関連付け
一部の銀行では、未加工の口座番号ではなくトークン化された口座番号 (TAN) を使用しているため、口座の再関連付けを行うと、関連付けられていた決済手段データが更新されます。ユーザーが Chase または PNC の口座を再度関連付けると、決済手段に元々関連付けられていた口座番号が自動的に更新されます。
オプションその他すべてのユースケースで Financial Connections アカウントのデータアクセスを修復する
セッションを作成する
Financial Connections Session を作成し、以下を指定します。
account_を顧客のholder[customer] idに設定します。- データの
permissionsパラメーターを設定してpayment_を組み込み、口座について取得するデータを設定します。permissions パラメーターは、method [payment_などの値が含まれる配列です。ユーザーのデータのプライバシーを保護するために、アクセスできる口座データはmethod, balances, ownership, transactions] permissionsパラメーターで指定したデータに制限されます。ユースケースに対応するために必要なデータを慎重に検討して、必要なデータのみにアクセスするための権限をリクエストします。認証フローが完了すると、permissions パラメーターで指定されたデータがユーザーに表示され、ユーザーはこのデータを共有するための同意を提供します。以下のコード例は、balancesとpayment_を収集する方法を示しています。method relink_を承認 ID に設定して、データアクセスを修復する口座の承認を指定します。options[authorization]
このリクエストでは、次のようなレスポンスが返されます。
{ "id": "fcsess_abcd", "object": "financial_connections.session", "livemode": true, "account_holder": { "customer": "cus_NfjonN9919dELB", "type": "customer" }, "accounts": [], "client_secret": "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh", "permissions": [ "payment_method", "balances" ], "relink_options": { "authorization": "fcauth_1LDYuMGxLVUXRs6HW0lrat9T" } }
Financial Connections アカウントを再度関連付ける
返された client_ を Stripe.js で使用して、ユーザーが口座の関連付けを変更できるようにします。client_ により、クライアント側の Stripe SDK は Financial Connections Session を変更できます。これは、保存したり、ログに記録したり、URL に埋め込んだり、当該エンドユーザー以外の人に公開したりしないでください。client secret が含まれるすべてのページで TLS を有効化するのを忘れないでください。
口座を収集するには、stripe. を使用します。
// Fetch existing accounts on the authorization to determine whether the linked account is new. const existing_account_ids = await fetch_existing_accounts(); const financialConnectionsSessionResult = await stripe.collectFinancialConnectionsAccounts({ clientSecret: "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh" });
stripe. の戻り値は Promise です。ユーザーが認証フローを完了すると、Promise は、関連付けの変更後の口座のリストを含むオブジェクトで解決されます。
stripe.collectFinancialConnectionsAccounts(client_secret).then(({session, error}) => { if (error) { // The session failed for some reason. console.error(error.message); } else if (session.accounts.length > 0) { // User has reauthorized existing Financial Connections accounts. reload_accounts(session.accounts); } else if (accounts.length == 0) { // The session failed to connect an account. } });
ユーザーがデータ共有する口座を関連付けている場合、accounts の長さは > 0 です。
エンドユーザーの金融機関の OAuth フロー内で、ユーザーは最初に関連付けたものとは別の口座を選択することができます。