# 決済または入金に使用される Financial Connections アカウントを関連付け直します。 非アクティブなアカウントを再アクティブ化して、データの取得、トークン化されたアカウント番号の再アクティブ化、データ権限の更新を行います。 [複数の理由](https://docs.stripe.com/financial-connections/relink.md)により、顧客が以前に関連付けられた [Financial Connections アカウント](https://docs.stripe.com/api/financial_connections/accounts/object.md)を再オーソリしなければならない場合があります。たとえば、データアクセスを回復するためのアカウントの再有効化、無効化された[トークン化アカウント番号](https://docs.stripe.com/financial-connections/tokenized-account-numbers.md)の更新などです。 Financial Connections アカウントを使用して決済または入金の銀行アカウントの詳細を確認する場合は、再リンクセッションを設定して、対象となるアカウントを 1 つ収集します。以下を実行できます。 - [特定の Financial Connections アカウントを再度関連付ける](https://docs.stripe.com/financial-connections/relink/api/payments-or-payouts.md#relink-specific-account) - [同じ金融機関の適格な Financial Connections アカウントを再度関連付ける](https://docs.stripe.com/financial-connections/relink/api/payments-or-payouts.md#relink-any-eligible-account) ## 口座が非アクティブになる時点を把握する [サーバー側] 顧客の関連付けられた Financial Connections アカウントは、次のような理由で無効になる場合があります。 - 金融機関から Stripe に提供された [OAuth](https://docs.stripe.com/financial-connections/fundamentals.md#how-stripe-links-financial-accounts) トークンは、一定期間の経過後、または操作が行われていないことを理由として有効期限が切れます。 - 金融機関が多要素認証 (MFA) の要求など、認証要件を変更するか、顧客がユーザー名とパスワードを変更する。 - 顧客がオンラインバンキングポータルからアクセスを取り消す。 - 顧客が金融機関の口座を解約する。 Financial Connections アカウントが非アクティブになると、`financial_connections.account.deactivated` [Webhook](https://docs.stripe.com/financial-connections/webhooks.md) でお知らせいたします。非アクティブな Financial Connections アカウントは、`status_details.inactive` サブハッシュに追加のステータスメタデータを含めます。 非アクティブなアカウントの根本的な原因をすべて修復することはできません。たとえば、顧客がアカウントを再開しない限り、解約されたアカウントを修復することはできません。修復できないアカウントの `status_details.inactive.action` は `none` です。 Financial Connections [アカウントを取得](https://docs.stripe.com/api/financial_connections/accounts/retrieve.md)して、いつでもステータスを確認できます。 - `status_details.inactive.cause` プロパティには、Financial Connections アカウントが非アクティブである大まかな理由が含まれます。たとえば、アカウントの OAuth 接続が期限切れになると、そのステータスは `access_expired` になります。 - `status_details.inactive.action` プロパティには、アカウントを再有効化するために実行するアクション (ある場合) が含まれます。顧客が再リンク認証フローを完了してアカウントを再有効化できる場合、そのステータスは `relink_required` です。 `status_details.inactive.action` が `relink_required` の場合は、顧客に認証フローを完了してアカウントを再度有効にするように求めます。 たとえば、次のような Webhook ハンドラを作成して、Webhook イベントを処理できます。 #### Python ```python import stripe import requests as r from requests.auth import HTTPBasicAuth # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. client = stripe.StripeClient('<>', stripe_version='2026-04-22.preview') # If you are testing your webhook locally with the Stripe CLI you # can find the endpoint's secret by running `stripe listen` # Otherwise, find your endpoint's secret in your webhook settings in # the Developer Dashboard endpoint_secret = 'whsec_...' @app.route('/webhook', methods=['POST']) def webhook(): event = None payload = request.data sig_header = request.headers["STRIPE_SIGNATURE"] try: event = client.construct_event(payload, sig_header, endpoint_secret) except ValueError as e: # Invalid payload raise e except stripe.error.SignatureVerificationError as e: # Invalid signature raise e if event["type"] == "financial_connections.account.deactivated": account = event["data"]["object"] if account["status"] == "inactive": if "status_details" in account: if account["status_details"]["inactive"]["action"] == "relink_required": prompt_user_to_relink(account) else: # if account does not have "status_details", check that the event destination is configured with the most recent public preview API version else: # No action to be taken. return jsonify(success=True) ``` アカウントの`ステータス`と `status_details` は、Financial Connections アカウントを取得するときにも確認できます。 ```curl curl https://api.stripe.com/v1/financial_connections/accounts/{{FINANCIALCONNECTIONSACCOUNT_ID}} \ -u "<>:" \ -H "Stripe-Version: 2026-04-22.preview" ``` ```json { "id": "{{ACCOUNT_ID}}", "object": "financial_connections.account", //..., "authorization": "{{AUTHORIZATION_ID}}", "status": "inactive", "status_details": { "inactive": { "action": "relink_required", "cause": "access_expired" } } } ``` ## 特定の Financial Connections アカウントを再度関連付ける [サーバー側] [クライアント側] `relink_options.authorization` と `relink_options.account` を指定して、認証フローで顧客が `relink_options.account` で指定された Financial Connections アカウントを選択するように要求する再リンクセッションを作成します。このセッションは、顧客がその正確なアカウントを再度関連付けた場合にのみ、関連付けられたアカウントで成功します。既存の Financial Connections アカウントを使用して作成されたリソースは、新しいトークン化されたアカウント番号など、関連付けられたアカウントの詳細で自動的に更新されます。実装で同じアカウントを必要としない場合は、顧客が[同じ金融機関で新しいアカウントを関連付けること](https://docs.stripe.com/financial-connections/relink/api/payments-or-payouts.md#relink-any-eligible-account)を許可できます。 Financial Connections セッションを作成し、以下を指定します。 1. Financial Connections アカウントの `account_holder` フィールドと同じ値に `account_holder` を設定します。[2 ステップ確認](https://docs.stripe.com/payments/build-a-two-step-confirmation.md)フローがある場合、または Intent を作成する前に支払い詳細を[収集する場合](https://docs.stripe.com/payments/accept-a-payment-deferred.md)、Financial Connections アカウントに `account_holder` は存在しません。この場合、セッションの作成時に `account_holder` を `null` に設定します。 1. データの `permissions` パラメーターを設定して、`payment_method`、およびアカウントで取得するすべてのデータを含めます。`permissions` パラメーターは、`payment_method`、`balances`、`ownership`、`transactions` のいずれかを含む値を含む配列です。ユーザーのデータのプライバシーを保護するために、`permissions` パラメーターで指定したデータにのみアクセスできます。ユースケースに必要なデータを慎重に検討し、必要なデータのみにアクセスする権限をリクエストします。認証フローが完了すると、ユーザーは `permissions` パラメーターで指定されたデータを表示し、このデータを共有することに同意します。以下の例は、`balances` と `payment_method` を収集する方法を示しています。 1. `relink_options.authorization` パラメータを Financial Connections アカウントの `authorization` ID と同じ値に設定します。 1. `relink_options.account` パラメータを Financial Connections アカウントの ID に設定します。 ```curl curl https://api.stripe.com/v1/financial_connections/sessions \ -u "<>:" \ -d "account_holder[type]=customer" \ -d "account_holder[customer]={{CUSTOMER_ID}}" \ -d "permissions[]=payment_method" \ -d "permissions[]=balances" \ -d "relink_options[authorization]={{FINANCIALCONNECTIONSAUTHORIZATION_ID}}" \ -d "relink_options[account]={{FINANCIALCONNECTIONSACCOUNT_ID}}" ``` このリクエストでは、次のようなレスポンスが返されます。 ``` { "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": "{{AUTHORIZATION_ID}}", "account": "{{ACCOUNT_ID}}" } } ``` 1. 返された `client_secret` をクライアント側の Stripe SDK で使用して、ユーザーが口座を再リンクできるようにします。`client_secret` により、クライアント側の Stripe SDK は Financial Connections セッションを変更できます。これは、保存したり、ログに記録したり、URL に埋め込んだり、当該エンドユーザー以外の人に公開したりしないでください。Client Secret が含まれるすべてのページで TLS が有効になっていることを確認してください。 1. Stripe.js で、[collectFinancialConnectionsAccounts](https://docs.stripe.com/js/financial_connections/collect_financial_connections_accounts) を使用してアカウントを収集します。`collectFinancialConnectionsAccounts` の戻り値は Promise です。ユーザーが認証フローを完了すると、Promise は `relink_result` サブオブジェクトを含むオブジェクトで解決されます。成功すると、再関連付けられたアカウントのリストも含まれます。 ```js const {financialConnectionsSession, error} = await stripe.collectFinancialConnectionsAccounts({ clientSecret: "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh" }); if (financialConnectionsSession) { if (financialConnectionsSession.relink_result.account) { // relink successful const relinkedAccount = financialConnectionsSession.accounts[0]; } else { switch (financialConnectionsSession.relink_result.failure_reason) { case 'no_account': // user successfully authenticated with their bank, but did not link the expected account break; case 'no_authorization': // user did not successfully authenticate with their bank break; case 'other': // unexpected failure break; } } } ``` 顧客が金融機関で認証しても、Financial Connections の認証フローにエラーが表示されることがあります。この場合、`relink_result.account` は設定されません。これは、選択したアカウントと `relink_options.account` で指定されたアカウントを照合できないためです。この場合、次のいずれかをお勧めします。 - 顧客に新しい決済手段または外部の銀行アカウントの設定を依頼する。 - Financial Connections セッションを使用して再試行するように顧客に求めます。このセッションでは、[同じ機関の任意の対象アカウント](https://docs.stripe.com/financial-connections/relink/api/payments-or-payouts.md#relink-any-eligible-account)が許可されます。 ## Optional: 同じ金融機関の適格な Financial Connections アカウントを再度関連付ける [サーバー側] [クライアント側] 前のセクションで使用した `relink_options.account` パラメーターでは、顧客が特定の Financial Connections アカウントをリンクする必要があります。顧客が別のアカウントをリンクすると、認証フローでエラーメッセージが表示されます。 代わりに、`relink_options.authorization` のみを使用して再リンクセッションを作成できます。これにより、顧客は特定のアカウントを選択せずに、オーソリと同じ機関で認証するように求められます。`filters.account_subcategories` を使用して、顧客が当座預金口座または普通預金口座のみを選択できるように指定し、`limits.accounts` を使用して 1 つのアカウントのみを選択できるように制限します。 顧客が既存の Financial Connections アカウントを選択すると、その`ステータス`、`権限`、`account_numbers` が更新されます。既存の Financial Connections アカウントを使用して作成されたリソースは、新しいトークン化されたアカウント番号など、関連付けられたアカウントの詳細で自動的に更新されます。顧客が新しいアカウントを関連付けた場合は、それを使用して決済手段を作成できます。再リンク認証フローで新しいアカウントが選択されても、既存の決済手段は自動的に更新されません。 顧客が非アクティブなアカウントと同じ金融機関の決済または入金の対象となる Financial Connections アカウントをリンクできるようにするには、以下のようにします。 1. `relink_options.authorization` を修復対象の Financial Connections authorization ID に設定し、`limits.accounts` を `1` に設定し、`filters.account_subcategories` を `["checking", "savings"]` に設定して、Financial Connections セッションを作成します。 ```curl curl https://api.stripe.com/v1/financial_connections/sessions \ -u "<>:" \ -d "account_holder[type]=customer" \ -d "account_holder[customer]={{CUSTOMER_ID}}" \ -d "filters[account_subcategories][]=checking" \ -d "filters[account_subcategories][]=savings" \ -d "limits[accounts]=1" \ -d "permissions[]=payment_method" \ -d "permissions[]=balances" \ -d "relink_options[authorization]={{FINANCIALCONNECTIONSAUTHORIZATION_ID}}" ``` 1. 返された `client_secret` をクライアント側の Stripe SDK で使用して、ユーザーが口座を再リンクできるようにします。`client_secret` により、クライアント側の Stripe SDK は Financial Connections セッションを変更できます。これは、保存したり、ログに記録したり、URL に埋め込んだり、当該エンドユーザー以外の人に公開したりしないでください。Client Secret が含まれるすべてのページで TLS が有効になっていることを確認してください。 1. Stripe.js で、[collectFinancialConnectionsAccounts](https://docs.stripe.com/js/financial_connections/collect_financial_connections_accounts) を使用してアカウントを収集します。`collectFinancialConnectionsAccounts` の戻り値は Promise です。ユーザーが認証フローを完了すると、Promise は `relink_result` サブオブジェクトを含むオブジェクトで解決されます。成功すると、再関連付けられたアカウントのリストも含まれます。 1. 関連付けられたアカウントのリストをクライアント側に渡して、顧客が再リンク認証フローで新しいアカウントを関連付けたかどうかを判断します。 ```js // Fetch existing accounts, or embed them in the server-rendered HTML const existingAccountIds = await fetchExistingAccounts(); const {financialConnectionsSession, error} = await stripe.collectFinancialConnectionsAccounts({ clientSecret: "fcsess_client_secret_UsESkKYzeiRcivgDJZfxZRFh" }); const linkedAccount = financialConnectionsSession?.accounts?.[0] if (linkedAccount) { const isNew = existingAccountIds.includes(linkedAccount.id); } else { // user linked no accounts } ``` `relink_options.account` を渡す際に、顧客が新しいアカウントをリンクして次のエッジケースを処理できるようにすることを推奨します。 - 顧客が金融機関で認証した後、Stripe は利用可能な口座を認識できないことがあります。これが発生し、`relink_options.account` が設定されている場合、認証フローにエラーメッセージが表示されます。`relink_options.authorization` のみが設定されている場合、顧客は利用可能な口座から選択し、アカウントの関連付けフローに進むことができます。 - OAuth フローでは、顧客は金融機関の OAuth モーダルで最初に関連付けられた口座とは別のアカウントを選択できます。 ## Optional: 決済手段を作成する [サーバー側] [クライアント側] `relink_options.account` を指定していない再リンクセッションでは、新しい Financial Connections アカウントが作成される可能性があります。この場合、既存の Financial Connections アカウントから作成された決済手段は更新されません。 #### 決済 `SetupIntent` を使用して、Financial Connections アカウントを使用し `PaymentMethod` を作成します。`customer` プロパティーを Financial Connections アカウントの `account_holder.customer` と同じ値に設定します。Financial Connections アカウントに `account_holder` 値がない場合は、`customer` プロパティーを設定しないでください。 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_data[type]=us_bank_account" \ -d "payment_method_data[us_bank_account][financial_connections_account]={{FINANCIALCONNECTIONSACCOUNT_ID}}" \ -d "payment_method_data[billing_details][name]=Jenny Rosen" ``` これにより、`ステータス`が `requires_confirmation` の SetupIntent が作成されます。顧客に [ACH 同意書](https://docs.stripe.com/payments/ach-direct-debit.md#mandates)を示し、Stripe クライアントライブラリを使用して SetupIntent を[確定し](https://docs.stripe.com/js/setup_intents/confirm_us_bank_account_setup)、同意書データを収集します。 ```html
``` [ACH 決済の受け付け](https://docs.stripe.com/payments/ach-direct-debit.md)についてもっと読む。 #### 入金 SetupIntent を使用して、Financial Connections アカウントを使用して PaymentMethod を作成し、確定します。`customer` プロパティを Financial Connections アカウントの `account_holder.customer` と同じ値に設定します。Financial Connections アカウントに `account_holder` 値がない場合は、`customer` プロパティを設定しないでください。 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "flow_directions[]=outbound" \ -d "payment_method_types[]=us_bank_account" \ -d confirm=true \ -d "payment_method_data[type]=us_bank_account" \ -d "payment_method_data[us_bank_account][financial_connections_account]={{FINANCIALCONNECTIONSACCOUNT_ID}}" \ -d "payment_method_data[billing_details][name]=Jenny Rosen" ``` 次に、SetupIntent に関連付けられた `payment_method` を使用して銀行口座トークンを作成します。SetupIntent の作成時に`顧客`を指定した場合は、トークンの作成時にも指定します。 ```curl curl https://api.stripe.com/v1/tokens \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "bank_account[payment_method]={{PAYMENTMETHOD_ID}}" ``` [Connect Payouts](https://docs.stripe.com/connect/payouts-bank-accounts.md?bank-account-collection-integration=direct-api) の詳細をご覧ください。 ## Optional: Financial Connections オーソリを取得する Financial Connections アカウントには、[Financial Connections オーソリ](https://docs.stripe.com/api/financial_connections/authorizations/object.md)リソースに対応する`オーソリ`プロパティがあります。オーソリリソースは、オーソリのすべてのアカウントのデータ接続の全体的なステータスを示します。複数のアカウントが同じオーソリを参照している場合、1 つのアカウントを再度関連付けると、同じオーソリの他のアカウントが再度アクティブになることがあります。これは想定内であり、以下の場合にのみ導入に影響します。 1. `financial_connections.account.reactivated` イベントをリッスンする Webhook エンドポイントがある。 1. ユーザーが 1 つのアカウントを選択しなければならない再リンクセッションが、1 つのアカウントのみを再有効化することを想定したビジネスロジックがある。 オーソリを取得してステータスを確認します。 ```curl curl https://api.stripe.com/v1/financial_connections/authorizations/{{FINANCIALCONNECTIONSAUTHORIZATION_ID}} \ -u "<>:" \ -H "Stripe-Version: 2026-04-22.preview" ``` ```json { "id": "{{AUTHORIZATION_ID}}", "object": "financial_connections.authorization", "account_holder": { "customer": "cus_TnvzdXv6VwjyrN", "type": "customer" }, "institution": "fcinst_Qn1a6jqpI0Gb84", "institution_name": "StripeBank", "livemode": false, "status": "active", "status_details": {} } ``` ## テスト Financial Connections を使用してテスト用銀行口座を接続する方法は、[テストガイド](https://docs.stripe.com/financial-connections/testing.md)に従います。非アクティブなアカウントでテストするには、認証フローで `Inactive accounts` 機関を検索し、指定された銀行口座を接続します。トークン化された口座番号を更新する動作をテストするには、認証フローで `Tokenized Account Numbers` 機関を検索し、指定された銀行口座を接続します。