Manage bank accounts with Tokenized Account Numbers

Avant de commencer

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.

Tokenized Account Numbers (TANs) are temporary bank account credentials issued by financial institutions instead of real account numbers. Today, Chase and PNC Bank issue TANs and US Bank will begin issuing TANs on November 30, 2025.

TANs behave similarly to real account and routing numbers, and you can use them to accept ACH payments and send payouts only 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.

These are the differences between real account numbers vs TANs:

TANs become deactivated in two scenarios:

• 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 available to the customer at any time.
• Expiry: The TAN expires after some amount of time set by the institution.

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.

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.

curl https://api.stripe.com/v1/financial_connections/accounts/fca_zbyrdjTrwcYZJZc6WBs6GPid \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

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.

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

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 returns 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 blocks the payment before the ACH transaction is submitted to the network because Stripe expects 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.

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: