Manage bank accounts with Tokenized Account Numbers

Learn about tokenized account numbers, their impact on your integration, and how to manage TAN accounts.

Tokenized Account Numbers (TANs) are temporary bank account credentials issued by financial institutions instead of real account numbers. Chase, PNC Bank, and US Bank issue TANs.

Before you begin

1. Understand Financial Connections fundamentals
2. Read about Financial Connections Account webhook events to understand how to receive updates about changes to Financial Connections Accounts.

How TANs work

TANs behave similarly to real account and routing numbers, and you can use them to accept ACH payments and send payouts when their status is active. Unlike real account numbers, a TAN can be deactivated, which can cause subsequent ACH transactions on the Financial Connections Account to fail.

Note

TAN behavior varies by financial institution. Some banks support customer revocation and expiration, while others don’t. To view specific behavior by institution, see TAN details by bank.

Compare real account numbers with TANs

These are the differences between real account numbers and TANs:

Deactivated TANs

TANs can become deactivated, depending on the issuing bank’s policies. To avoid payment failures, you can handle deactivated TANs.

Common deactivation scenarios include:

• Revocation : When a customer actively revokes access to their account data using their financial institution’s online banking portal (such as through the Chase Security center). This option is only available at some institutions.
• Expiry : The TAN expires after an amount of time set by the institution. Not all banks implement time-based expiration.

After a TAN is deactivated, your customer needs to link their bank account again or link a different bank account to make sure they can continue to make payments or receive payouts.

To learn which institutions support revocation and expiry, see TAN details by bank.

How to manage TANs

Display real account details to your customer in your UI

If you display account identifiers to help customers recognize and select a bank account in your application, display the last4 field from the Financial Connections Account object. This field shows the last four digits of the real account number, regardless of whether the institution uses TANs or real account numbers.

Identify Financial Connections Accounts with TANs and their status

Use the Financial Connections API to determine whether a bank account has a TAN or a real account number, and whether that TAN can be used for ACH transactions.

To determine if a Financial Connections Account has a TAN, reference the identifier_type field on the objects in the account_numbers array, which is set to tokenized_account_number if the account number is a TAN. The identifier_type of a real account number is set to account_number.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

This example request returns a Financial Connections Account with information about a TAN.

{
 "id": "fca_zbyrdjTrwcYZJZc6WBs6GPid",
 "object": "financial_connections.account",
 "account_holder": {
 "customer": "cus_NfjonN9919dELB",
 "type": "customer"
 },
 "institution_name": "PNC Bank",
 "status": "active",
 "account_numbers": [
 {
 "identifier_type": "tokenized_account_number",
 "expected_expiry_date": null,
 "status": "transactable",
 "supported_networks" : ["ach"]
 }
 ]
}

In the request, check the status of the TAN. A TAN’s status is either:

It’s possible for a Financial Connections Account to have an active status even if its TAN is deactivated if the Account is still usable for bank data refreshes.

Note

PNC Bank expired some accounts between August 18 and September 9, 2025 before instituting a pause to 1-year rolling expiries. Time-based expiry might resume as banks evolve their TAN policies.

Banks might add time-based expiration rules to TANs. If TANs are set to expire by a bank, you can:

1. Reference the expected _ expiry _ date field. It displays the date of expiration.
2. Listen for the financial _ connections. account. upcoming _ account _ number _ expiry webhook event, which Stripe sends 30 days before the TAN is set to expire.

Handle deactivated TANs

This guide describes how to manage TANs deactivation for either:

• ACH Direct Debit payments
• External bank accounts used for payouts

Note

If you haven’t already, you need to set up a webhook endpoint (use the Webhooks page in the Dashboard or follow the webhook guide) to listen to the applicable events for your integration.

ACH Direct Debit payments

ACH Direct Debit PaymentMethods become unusable when the account’s associated TAN is deactivated. Handle TAN deactivations in your ACH Direct Debits integration to avoid payment failures.

When a bank account with a TAN used for an ACH Direct Debit PaymentMethod is deactivated, Stripe sends a payment_method.automatically_updated event.

To identify PaymentMethods with deactivated TANs in your webhook handler, check if the PaymentMethod’s payment_method.us_bank_account.status_details.blocked.reason field is set to tokenized_account_number_deactivated.

If you attempt to confirm a ACH Direct Debit payment with a deactivated TAN, Stripe might return a bank_account_unusable error. If this error occurs while your customer is on session, you must collect a new payment method. Unlike an ACH return, Stripe attempts to block the payment before the ACH transaction is submitted to the network if we expect the transaction to fail due to a deactivated TAN. This means the payment failed at the time of payment submission, rather than 2 to 3 days later, and helps you avoid any failed payment fees.

Avoid processing deactivated TANs

ACH payments processed off of Stripe using the deactivated TAN will also fail, but your processor might not reject the payment at the time of submission. You must avoid submitting payments on deactivated TANs to avoid downstream failures.

To ensure future payments succeed, recollect the bank account or collect a new bank account from your customer and create a new PaymentMethod.

External bank accounts

External Bank Accounts that have been linked with Financial Connections become unusable when a TAN is deactivated. Handle TAN deactivations in your payouts integration to avoid payout failures.

When a bank account with a TAN is deactivated for an External Bank Account, Stripe sends an account.external_account.updated webhook event.

To determine if Stripe sent the account.external_account.updated event has been sent because of a deactivated TAN, in your webhook handler verify that the External Bank Account’s status field is set to tokenized_account_number_deactivated.

To ensure future payouts succeed, recollect the bank account or a new bank account from your customer and create a new External Bank Account.

TAN details by bank

The following institutions return TANs when your customers link accounts through Financial Connections:

Delayed activation of tokenized account numbers

US Bank and PNC tokenized account numbers take up to 45 minutes to activate after they’re issued, and banks might reject payments submitted immediately. If you process ACH payments with Stripe, we handle the delayed activation automatically. If you process ACH payments off of Stripe, wait 90 minutes after issuance before submitting ACH transfers.

See also

• Test TAN behavior