# Adds support for handling tokenized bank account numbers ## What’s new Adds ways to help you manage tokenized bank account numbers (TANs) through the API. TANs are temporary bank account credentials issued by financial institutions instead of real account numbers, and can be used for ACH payments and payouts while they’re active. When a TAN is deactivated, through expiration or revocation, subsequent transfers using the bank account fail. ### Financial Connections Adds an [account_numbers](https://docs.stripe.com/api/financial_connections/accounts/object.md?api-version=2025-11-17.clover#financial_connections_account_object-account_numbers) property to the [Financial Connections Accounts](https://docs.stripe.com/api/financial_connections/accounts.md?api-version=2025-11-17.clover) to provide information about tokenized bank account numbers. This includes details about account number expiration dates and whether an account uses a tokenized account number (TAN). We also introduce two new events to help you stay informed about account number changes: - [financial_connections.account.account_numbers_updated](https://docs.stripe.com/api/events/types.md?api-version=2025-11-17.clover#event_types-financial_connections.account.account_numbers_updated): We send this event when the account number information changes for a Financial Connections account. - [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): We send this event when a tokenized account number is approaching its expiration date. ### Payments and Topups Adds a new enum value `tokenized_account_number_deactivated` to the [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) property. When a bank account becomes blocked, its tokenized account number (TAN) has been deactivated by the partner bank. The `blocked_reason` property provides specific information to help you understand why the bank account can no longer be used as a payment method. You can listen for the [payment_method.automatically_updated](https://docs.stripe.com/api/events/types.md?api-version=2025-11-17.clover#event_types-payment_method.automatically_updated) event to be notified when this bank account becomes blocked as a payment method. ### Payouts Adds a new value `tokenized_account_number_deactivated` to the [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). You can listen for the [account.external_account.updated](https://docs.stripe.com/api/events/types.md?api-version=2025-11-17.clover#event_types-account.external_account.updated) event to be notified when an external bank account’s status changes to `tokenized_account_number_deactivated`. ## Impact You can now identify when bank accounts connected through [Financial Connections](https://docs.stripe.com/financial-connections.md) use tokenized account numbers and understand their status. This helps you proactively manage payment and payout failures that can occur when tokenized account numbers become deactivated. If your integration processes ACH payments or payouts using Financial Connections accounts, you can use this information to prompt customers to reconnect their accounts before tokenized numbers expire, helping avoid failed transactions and associated fees. The new events enable you to build automated workflows that notify customers or update your systems when account number information changes or when expiration is approaching. ## Changes #### 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` | ## Upgrade #### REST API 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 1. If you use an SDK, upgrade to the corresponding SDK version for this API version. - If you don’t use an SDK, update your [API requests](https://docs.stripe.com/api/versioning.md) to include `Stripe-Version: 2025-11-17.clover` 1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 1. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### Ruby 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 1. Upgrade your Ruby SDK to [v17.2.0](https://github.com/stripe/stripe-ruby/releases/tag/v17.2.0) 1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 1. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### Python 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 1. Upgrade your Python SDK to [v13.2.0](https://github.com/stripe/stripe-python/releases/tag/v13.2.0) 1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 1. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### PHP 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 1. Upgrade your PHP SDK to [v18.2.0](https://github.com/stripe/stripe-php/releases/tag/v18.2.0) 1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 1. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### Java 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 1. Upgrade your Java SDK to [v30.2.0](https://github.com/stripe/stripe-java/releases/tag/v30.2.0) 1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 1. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### Node.js 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 1. Upgrade your Node SDK to [v19.3.0](https://github.com/stripe/stripe-node/releases/tag/v19.3.0) 1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 1. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### Go 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 1. Upgrade your Go SDK to [v83.2.0](https://github.com/stripe/stripe-go/releases/tag/v83.2.0) 1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 1. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md). #### .NET 1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench. 1. Upgrade your .NET SDK to [v49.2.0](https://github.com/stripe/stripe-dotnet/releases/tag/v49.2.0) 1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md). 1. [Test your integration](https://docs.stripe.com/testing.md) against the new version. 1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md). 1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours. Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).