# トークン化された銀行アカウント番号の処理のサポートを追加する

## 新機能

API を使用してトークン化された銀行口座番号 (TAN) を管理する方法を追加します。TAN は、実際のアカウント番号の代わりに金融機関が発行する一時的な銀行口座の認証情報であり、有効な間は ACH 支払いと入金に使用できます。TAN が無効になるか、有効期限が切れたり、取り消されたりすると、その銀行口座を使用した以降の送金は失敗します。

### Financial Connections

トークン化された銀行口座番号に関する情報を提供する [account_numbers](https://docs.stripe.com/api/financial_connections/accounts/object.md?api-version=2025-11-17.clover#financial_connections_account_object-account_numbers) プロパティを [Financial Connections アカウント](https://docs.stripe.com/api/financial_connections/accounts.md?api-version=2025-11-17.clover)に追加します。これには、アカウント番号の有効期限と、アカウントがトークン化されたアカウント番号 (TAN) を使用するかどうかの詳細が含まれます。

また、アカウント番号の変更に関する情報を把握しやすくするために、2 つの新しいイベントが導入されました。

- [financial_connections.account.account_numbers_up](https://docs.stripe.com/api/events/types.md?api-version=2025-11-17.clover#event_types-financial_connections.account.account_numbers_updated): Financial Connections アカウントの口座番号情報が変更されたときにこのイベントが送信されます。
- [financial_connections.account.upcoming_account_number_expiry](https://docs.stripe.com/api/events/types.md?api-version=2025-11-17.clover#event_types-financial_connections.account.upcoming_account_number_expiry): このイベントは、トークン化された口座番号の有効期限が近づいたときに送信されます。

### 決済とトップアップ

[payment_method_us_bank_account_blocked.reason](https://docs.stripe.com/api/payment_methods/object.md?api-version=2025-11-17.clover#payment_method_object-us_bank_account-status_details-blocked-reason) プロパティに、新しい列挙値 `tokenized_account_number_deactivated` を追加します。銀行口座が、パートナー銀行によってトークン化された口座番号 (TAN) が無効化されたためにブロックされた場合、`blocked_reason` プロパティによって、その銀行口座が支払い方法として使用できなくなった理由を把握できるように、特定の情報が表示されるようになりました。

この銀行口座が支払い方法としてブロックされた場合に通知される[payment_method.automatically_updated](https://docs.stripe.com/api/events/types.md?api-version=2025-11-17.clover#event_types-payment_method.automatically_updated)イベントをリッスンできます。

### 入金

新しい値 `tokenized_account_number_deactivated` を [bank_account.status](https://docs.stripe.com/api/external_account_bank_accounts/object.md?api-version=2025-11-17.clover#account_bank_account_object-status) に追加します。

[account.external_account.updated](https://docs.stripe.com/api/events/types.md?api-version=2025-11-17.clover#event_types-account.external_account.updated) イベントをリッスンして、外部の銀行口座のステータスが `tokenized_account_number_deactivated` に変わったときに通知を受け取ることができます。

## 影響

[Financial Connections](https://docs.stripe.com/financial-connections.md) を介して連結された銀行口座がトークン化された口座番号を使用するタイミングを特定し、そのステータスを把握できるようになりました。これにより、トークン化された口座番号が無効になったときに発生する支払いと入金の失敗を事前に管理できます。

連携で Financial Connections アカウントを使用して ACH 決済または Payouts を処理している場合は、トークン化された番号の有効期限が切れる前にこの情報を使用して顧客にアカウントを再連結するように促すことで、取引の失敗や関連手数料を回避できます。

イベントを使用すると、アカウント番号情報が変更されたとき、または有効期限が近づいたときに、顧客に通知したり、システムを更新したりする自動化ワークフローを構築できます。

## 変更点

#### REST API

| Values                                                                                                                  | Change | Enums                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ----------------------------------------------------------------------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tokenized_account_number_deactivated`                                                                                  | Added  | [ConfirmationToken.payment_method_preview.us_bank_account.status_details.blocked](/api/confirmation_tokens/object?api-version=2025-11-17.clover#confirmation_token_object-payment_method_preview-us_bank_account-status_details-blocked-reason), [PaymentMethod.us_bank_account.status_details.blocked](/api/confirmation_tokens/object?api-version=2025-11-17.clover#confirmation_token_object-us_bank_account-status_details-blocked-reason)                                    |
| `financial_connections.account.account_numbers_updated`, `financial_connections.account.upcoming_account_number_expiry` | Added  | [Event](/api/events/object?api-version=2025-11-17.clover#event_object-type), [FinancialConnections.Account](/api/financial_connections/accounts/object?api-version=2025-11-17.clover), [WebhookEndpoint#update](/api/webhook_endpoints/update?api-version=2025-11-17.clover#update_webhook_endpoint-enabled_events), [WebhookEndpoint#create](/api/webhook_endpoints/update?api-version=2025-11-17.clover#update_webhook_endpoint-enabled_events), `FinancialConnections.Account` |

#### Ruby

| Parameter         | Change | Resources or methods                                                                                      |
| ----------------- | ------ | --------------------------------------------------------------------------------------------------------- |
| `account_numbers` | Added  | [FinancialConnections::Account](/api/financial_connections/accounts/object?api-version=2025-11-17.clover) |

#### Python

| Values                                                                                                                  | Change | Enums                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tokenized_account_number_deactivated`                                                                                  | Added  | [ConfirmationToken.PaymentMethodPreview.UsBankAccount.StatusDetail.Blocked](/api/confirmation_tokens/object?api-version=2025-11-17.clover#confirmation_token_object-payment_method_preview-us_bank_account-status_details-blocked-reason), [PaymentMethod.UsBankAccount.StatusDetail.Blocked](/api/confirmation_tokens/object?api-version=2025-11-17.clover#confirmation_token_object-us_bank_account-status_details-blocked-reason)                                                         |
| `financial_connections.account.account_numbers_updated`, `financial_connections.account.upcoming_account_number_expiry` | Added  | [Event](/api/events/object?api-version=2025-11-17.clover#event_object-type), [FinancialConnections.Account](/api/financial_connections/accounts/object?api-version=2025-11-17.clover), [WebhookEndpointModifyParams](/api/webhook_endpoints/update?api-version=2025-11-17.clover#update_webhook_endpoint-enabled_events), [WebhookEndpointCreateParams](/api/webhook_endpoints/update?api-version=2025-11-17.clover#update_webhook_endpoint-enabled_events), `financial_connections.Account` |

#### PHP

| Values                                                                                                                  | Change | Enums                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tokenized_account_number_deactivated`                                                                                  | Added  | [ConfirmationToken.payment_method_preview.us_bank_account.status_details.blocked](/api/confirmation_tokens/object?api-version=2025-11-17.clover#confirmation_token_object-payment_method_preview-us_bank_account-status_details-blocked-reason), [PaymentMethod.us_bank_account.status_details.blocked](/api/confirmation_tokens/object?api-version=2025-11-17.clover#confirmation_token_object-us_bank_account-status_details-blocked-reason) |
| `financial_connections.account.account_numbers_updated`, `financial_connections.account.upcoming_account_number_expiry` | Added  | [Event](/api/events/object?api-version=2025-11-17.clover#event_object-type), [FinancialConnections.Account](/api/financial_connections/accounts/object?api-version=2025-11-17.clover), `FinancialConnections.Account`                                                                                                                                                                                                                          |

#### Java

| Parameter        | Change | Resources or methods                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `accountNumbers` | Added  | [financialconnections.Account](/api/financial_connections/accounts/object?api-version=2025-11-17.clover), [WebhookEndpointUpdateParams](/api/webhook_endpoints/update?api-version=2025-11-17.clover#update_webhook_endpoint-enabledEvents), [WebhookEndpointCreateParams](/api/webhook_endpoints/update?api-version=2025-11-17.clover#update_webhook_endpoint-enabledEvents), `financialconnections.Account` |

#### Node.js

| Values                                                                                                                  | Change | Enums                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tokenized_account_number_deactivated`                                                                                  | Added  | [ConfirmationToken.payment_method_preview.us_bank_account.status_details.blocked](/api/confirmation_tokens/object?api-version=2025-11-17.clover#confirmation_token_object-payment_method_preview-us_bank_account-status_details-blocked-reason), [PaymentMethod.us_bank_account.status_details.blocked](/api/confirmation_tokens/object?api-version=2025-11-17.clover#confirmation_token_object-us_bank_account-status_details-blocked-reason)                                              |
| `financial_connections.account.account_numbers_updated`, `financial_connections.account.upcoming_account_number_expiry` | Added  | [Event](/api/events/object?api-version=2025-11-17.clover#event_object-type), [FinancialConnections.Account](/api/financial_connections/accounts/object?api-version=2025-11-17.clover), [WebhookEndpointUpdateParams](/api/webhook_endpoints/update?api-version=2025-11-17.clover#update_webhook_endpoint-enabled_events), [WebhookEndpointCreateParams](/api/webhook_endpoints/update?api-version=2025-11-17.clover#update_webhook_endpoint-enabled_events), `FinancialConnections.Account` |

#### Go

| Values                                                                                                                  | Change | Enums                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tokenized_account_number_deactivated`                                                                                  | Added  | [ConfirmationTokenPaymentMethodPreviewUsBankAccountStatusDetailsBlocked](/api/confirmation_tokens/object?api-version=2025-11-17.clover#confirmation_token_object-payment_method_preview-us_bank_account-status_details-blocked-Reason), [PaymentMethodUsBankAccountStatusDetailsBlocked](/api/confirmation_tokens/object?api-version=2025-11-17.clover#confirmation_token_object-us_bank_account-status_details-blocked-Reason) |
| `financial_connections.account.account_numbers_updated`, `financial_connections.account.upcoming_account_number_expiry` | Added  | [Event](/api/events/object?api-version=2025-11-17.clover#event_object-Type), [FinancialConnectionsAccount](/api/financial_connections/accounts/object?api-version=2025-11-17.clover), `FinancialConnectionsAccount`                                                                                                                                                                                                             |

#### .NET

| Parameter        | Change | Resources or methods                                                                                                                     |
| ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `AccountNumbers` | Added  | [FinancialConnections.Account](/api/financial_connections/accounts/object?api-version=2025-11-17.clover), `FinancialConnections.Account` |

## アップグレード

#### REST API

1. Workbench で[現在の API バージョンを表示します](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench)。
1. SDK を使用している場合は、この API バージョンに対応する SDK バージョンにアップグレードします。
   - SDK を使用していない場合は、`Stripe-Version: 2025-11-17.clover` を含めるように [API リクエスト](https://docs.stripe.com/api/versioning.md)を更新してください。
1. [Webhook エンドポイント](https://docs.stripe.com/webhooks/versioning.md)に使用する API バージョンをアップグレードします。
1. 新しいバージョンに対して、[実装内容をテスト](https://docs.stripe.com/testing.md)します。
1. Connect を使用する場合は、[Connect の実装内容をテスト](https://docs.stripe.com/connect/testing.md)します。
1. Workbench で[アップグレードを実行](https://docs.stripe.com/upgrades.md#perform-the-upgrade)します。[バージョンをロールバック](https://docs.stripe.com/upgrades.md#roll-back-your-api-version)できるのは 72 時間以内です。

[Stripe API のアップグレード](https://docs.stripe.com/upgrades.md)について、詳細をご確認ください。

#### Ruby

1. Workbench で[現在の API バージョンを表示します](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench)。
1. Ruby SDK を [v17.2.0](https://github.com/stripe/stripe-ruby/releases/tag/v17.2.0)にアップグレードします。
1. [Webhook エンドポイント](https://docs.stripe.com/webhooks/versioning.md)に使用する API バージョンをアップグレードします。
1. 新しいバージョンに対して、[実装内容をテスト](https://docs.stripe.com/testing.md)します。
1. Connect を使用する場合は、[Connect の実装内容をテスト](https://docs.stripe.com/connect/testing.md)します。
1. Workbench で[アップグレードを実行](https://docs.stripe.com/upgrades.md#perform-the-upgrade)します。[バージョンをロールバック](https://docs.stripe.com/upgrades.md#roll-back-your-api-version)できるのは 72 時間以内です。

[Stripe API のアップグレード](https://docs.stripe.com/upgrades.md)について、詳細をご確認ください。

#### Python

1. Workbench で[現在の API バージョンを表示します](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench)。
1. Python SDK を [v13.2.0](https://github.com/stripe/stripe-python/releases/tag/v13.2.0)にアップグレードします。
1. [Webhook エンドポイント](https://docs.stripe.com/webhooks/versioning.md)に使用する API バージョンをアップグレードします。
1. 新しいバージョンに対して、[実装内容をテスト](https://docs.stripe.com/testing.md)します。
1. Connect を使用する場合は、[Connect の実装内容をテスト](https://docs.stripe.com/connect/testing.md)します。
1. Workbench で[アップグレードを実行](https://docs.stripe.com/upgrades.md#perform-the-upgrade)します。[バージョンをロールバック](https://docs.stripe.com/upgrades.md#roll-back-your-api-version)できるのは 72 時間以内です。

[Stripe API のアップグレード](https://docs.stripe.com/upgrades.md)について、詳細をご確認ください。

#### PHP

1. Workbench で[現在の API バージョンを表示します](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench)。
1. PHP SDK を [v18.2.0](https://github.com/stripe/stripe-php/releases/tag/v18.2.0)にアップグレードします。
1. [Webhook エンドポイント](https://docs.stripe.com/webhooks/versioning.md)に使用する API バージョンをアップグレードします。
1. 新しいバージョンに対して、[実装内容をテスト](https://docs.stripe.com/testing.md)します。
1. Connect を使用する場合は、[Connect の実装内容をテスト](https://docs.stripe.com/connect/testing.md)します。
1. Workbench で[アップグレードを実行](https://docs.stripe.com/upgrades.md#perform-the-upgrade)します。[バージョンをロールバック](https://docs.stripe.com/upgrades.md#roll-back-your-api-version)できるのは 72 時間以内です。

[Stripe API のアップグレード](https://docs.stripe.com/upgrades.md)について、詳細をご確認ください。

#### Java

1. Workbench で[現在の API バージョンを表示します](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench)。
1. Java SDK を [v30.2.0](https://github.com/stripe/stripe-java/releases/tag/v30.2.0)にアップグレードします。
1. [Webhook エンドポイント](https://docs.stripe.com/webhooks/versioning.md)に使用する API バージョンをアップグレードします。
1. 新しいバージョンに対して、[実装内容をテスト](https://docs.stripe.com/testing.md)します。
1. Connect を使用する場合は、[Connect の実装内容をテスト](https://docs.stripe.com/connect/testing.md)します。
1. Workbench で[アップグレードを実行](https://docs.stripe.com/upgrades.md#perform-the-upgrade)します。[バージョンをロールバック](https://docs.stripe.com/upgrades.md#roll-back-your-api-version)できるのは 72 時間以内です。

[Stripe API のアップグレード](https://docs.stripe.com/upgrades.md)について、詳細をご確認ください。

#### Node.js

1. Workbench で[現在の API バージョンを表示します](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench)。
1. Node SDK を [v19.3.0](https://github.com/stripe/stripe-node/releases/tag/v19.3.0)にアップグレードします。
1. [Webhook エンドポイント](https://docs.stripe.com/webhooks/versioning.md)に使用する API バージョンをアップグレードします。
1. 新しいバージョンに対して、[実装内容をテスト](https://docs.stripe.com/testing.md)します。
1. Connect を使用する場合は、[Connect の実装内容をテスト](https://docs.stripe.com/connect/testing.md)します。
1. Workbench で[アップグレードを実行](https://docs.stripe.com/upgrades.md#perform-the-upgrade)します。[バージョンをロールバック](https://docs.stripe.com/upgrades.md#roll-back-your-api-version)できるのは 72 時間以内です。

[Stripe API のアップグレード](https://docs.stripe.com/upgrades.md)について、詳細をご確認ください。

#### Go

1. Workbench で[現在の API バージョンを表示します](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench)。
1. Go SDK を [v83.2.0](https://github.com/stripe/stripe-go/releases/tag/v83.2.0)にアップグレードします。
1. [Webhook エンドポイント](https://docs.stripe.com/webhooks/versioning.md)に使用する API バージョンをアップグレードします。
1. 新しいバージョンに対して、[実装内容をテスト](https://docs.stripe.com/testing.md)します。
1. Connect を使用する場合は、[Connect の実装内容をテスト](https://docs.stripe.com/connect/testing.md)します。
1. Workbench で[アップグレードを実行](https://docs.stripe.com/upgrades.md#perform-the-upgrade)します。[バージョンをロールバック](https://docs.stripe.com/upgrades.md#roll-back-your-api-version)できるのは 72 時間以内です。

[Stripe API のアップグレード](https://docs.stripe.com/upgrades.md)について、詳細をご確認ください。

#### .NET

1. Workbench で[現在の API バージョンを表示します](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench)。
1. .NET SDK を [v49.2.0](https://github.com/stripe/stripe-dotnet/releases/tag/v49.2.0)にアップグレードします。
1. [Webhook エンドポイント](https://docs.stripe.com/webhooks/versioning.md)に使用する API バージョンをアップグレードします。
1. 新しいバージョンに対して、[実装内容をテスト](https://docs.stripe.com/testing.md)します。
1. Connect を使用する場合は、[Connect の実装内容をテスト](https://docs.stripe.com/connect/testing.md)します。
1. Workbench で[アップグレードを実行](https://docs.stripe.com/upgrades.md#perform-the-upgrade)します。[バージョンをロールバック](https://docs.stripe.com/upgrades.md#roll-back-your-api-version)できるのは 72 時間以内です。

[Stripe API のアップグレード](https://docs.stripe.com/upgrades.md)について、詳細をご確認ください。