トークン化された口座番号を使用して Financial Connections アカウントを管理

はじめに

1. Understand Financial Connections fundamentals
2. Financial Connections アカウント Webhook イベントを読み、Financial Connections アカウントの変更に関する更新を受け取る方法を確認します。

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:

• 取り消し: 顧客が金融機関のオンラインバンキンググポータル (Chase Security Center など) を使用して、アカウントデータへのアクセスを能動的に取り消した場合。顧客はいつでもこのオプションを使用できます。
• 有効期限: 機関が設定した一定の期間が経過した後に TAN の有効期限が切れた場合。

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.

非アクティブ化された TAN を処理する

This guide describes how to manage TANs deactivation for either:

• ACH ダイレクトデビットによる支払い
• 入金に使用される外部の銀行口座

ACH ダイレクトデビットによる支払い

アカウントの関連付けられている TAN が無効になると、ACH Direct Debit PaymentMethods が使用できなくなります。支払いの失敗を回避するには、ACH Direct Debit の導入で TAN の無効化を処理してください。

ACH Direct Debit PaymentMethodに使用されるTANの銀行口座が無効になると、Stripeはpayment_method.automatically_updatedイベントを送信します。

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 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

次の機関は、顧客が Financial Connections を介して口座を Link すると TAN を返します。