トークン化された口座番号による銀行口座の管理

はじめに

1. Financial Connections の基本について理解する
2. Financial Connections アカウント Webhook イベントを読み、Financial Connections アカウントの変更に関する更新を受け取る方法を確認します。

トークン化されたアカウント番号 (TAN) は、実際のアカウント番号の代わりに金融機関が発行する一時的な銀行アカウントの認証情報です。現在、Chase と PNC Bank は TAN を発行し、US Bank は 2025 年 11 月 30 日に TAN の発行を開始します。

TAN は実際のアカウント番号や経路の選定番号と同様に動作し、ステータスが有効な場合にのみ ACH 決済の受け付けや Payouts の送金に使用できます。実際のアカウント番号とは異なり、TAN は無効にできるため、Financial Connections アカウントでの以降の ACH 取引が失敗する可能性があります。

実際のアカウント番号と TAN の違いを次に示します。

TAN は、次の 2 つのシナリオで無効になります。

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

TAN が無効化された後、顧客は銀行アカウントを再度リンク付けるか、別の銀行アカウントをリンク付けて、決済や Payouts の受け取りを継続できるようにする必要があります。

TAN の管理方法

UI で顧客に実際のアカウントの詳細を表示する

アプリケーションで顧客が銀行口座を認識して選択できるようにアカウント ID を表示する場合は、Financial Connections アカウント オブジェクトの last4 フィールドを表示します。このフィールドには、金融機関が TAN と実口座番号のどちらを使用しているかに関係なく、実口座番号の末尾 4 桁が表示されます。

TAN を持つ Financial Connections アカウントとそのステータスを識別する

Financial Connections API を使用して、銀行口座に TAN または実際の口座番号があるかどうか、およびその TAN を ACH 取引に使用できるかどうかを判断します。

Financial Connections アカウント に TAN があるかどうかを判別するには、account_numbers 配列のオブジェクトの identifier_type フィールドを参照します。アカウント番号が TAN の場合は、tokenized_account_number に設定されます。実際のアカウント番号の identifier_type は account_number に設定されます。

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

このリクエスト例は、TAN に関する情報を含む Financial Connections アカウントを返します。

{
  "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"]
    }
  ]
}

リクエストで、TAN のステータスを確認します。TAN のステータスは次のいずれかです。

Financial Connections アカウントは、TAN が無効になっていても、銀行データの更新にアカウントが引き続き使用できる場合は、status はアクティブになる可能性があります。

銀行は、TAN に時間ベースの有効期限ルールを追加する場合があります。銀行によって TAN の有効期限が設定されている場合は、以下を実行できます。

1. expected_expiry_date フィールドを参照します。有効期限が表示されます。
2. TAN が期限切れになる 30 日前に Stripe から送信される financial_Connections.account.upcoming_account_number_expiry Webhook イベントをリッスンします。

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

このガイドでは、次のいずれかの TAN の無効化を管理する方法について説明します。

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

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

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

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

Webhook ハンドラーで非アクティブ化された TAN を含む PaymentMethod を識別するには、決済手段の payment_method.us_bank_account.status_details.blocked.reason フィールドが tokenized_account_number_deactivated に設定されているかどうかを確認します。

無効化された TAN で ACH Direct Debit 支払いを確定しようとすると、Stripe は bank_account_unusable エラーを返します。顧客のセッション中にこのエラーが発生した場合には、新しい決済方法を収集する必要があります。ACH の返金とは異なり、無効化された TAN が原因で ACH 取引が失敗すると Stripe が想定した場合には、ACH 取引がネットワークに送信される前にStripe が決済をブロックします。これにより決済の失敗が2 〜 3 日後ではなく支払い時に確定するため、決済失敗手数料の支払いを回避できます。

今後の決済を確実に成功させるには、銀行アカウントを再収集するか、顧客から新しい銀行アカウントを収集し、新しい PaymentMethod を作成します。

外部の銀行口座

Financial Connections に関連付けられていた外部銀行口座は、TAN が無効になると使用できなくなります。入金の失敗を回避するには、Payouts の導入で TAN の無効化を適切に処理してください。

TAN が設定された銀行口座が外部の銀行口座に対して無効化されると、Stripe は account.external_account.updated Webhook イベントを送信します。

TAN が無効化されたために account.external_account.updated イベントが送信されたかどうかを判断するには、Webhook ハンドラーで、外部銀行口座の status フィールドが tokenized_account_number_deactivated に設定されていることを確認します。

将来の Payouts を確実に成功させるには、顧客から銀行アカウントまたは新しい銀行アカウントを再収集し、新しい外部銀行アカウントを作成します。

TAN の詳細 (銀行別)

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

詳しくはこちら

• TAN の動作をテストする方法