口座を収集して、データを活用する商品を構築する

本番環境でのアクセスがアカウントに承認されたら、Financial Connections に登録してください。

アプリケーションから Stripe API にアクセスするには、Stripe の公式ライブラリを使用します。

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

ユーザーが貴社でアカウントを作成するときに、Customer (顧客) オブジェクト を作成します。メールアドレスを提供することで、 Financial Connections は Link のリピーターユーザーに効率的なユーザーインターフェイスを動的に表示し、認証フローを最適化できます。

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d email={{CUSTOMER_EMAIL}} \
  -d name={{CUSTOMER_NAME}}

Financial Connections を使用してユーザーの銀行口座からデータを取得するには、ユーザーが認証フローでその口座を認証する必要があります。

ユーザーは、口座をサイトまたはアプリケーションに関連付けるときに認証フローを開始します。ユーザーが口座を関連付けられるようにするボタン (銀行口座を関連付けるなど) またはリンクをサイトやアプリケーションに挿入します。

/v1/financial_connections/sessions に送信することで、Financial Connections Session を作成します。

curl https://api.stripe.com/v1/financial_connections/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "account_holder[type]"=customer \
  -d "account_holder[customer]"=
{{CUSTOMER_ID}} \
  -d "permissions[]"=balances \
  -d "permissions[]"=ownership \
  -d "permissions[]"=payment_method \
  -d "permissions[]"=transactions

1. account_holder[customer] を Customer の id に設定します。
2. ユースケースの実施に必要なデータを含めてデータの permissions パラメーターを設定します。
3. (オプション) アカウント作成時に、データ取得用の prefetch パラメーターを設定します。

permissions パラメーターは、アクセスできる口座データを管理します。少なくとも 1 つの権限をリクエストする必要があります。認証フローが完了すると、ユーザーはアクセスをリクエストしたデータを確認し、そのデータの共有に同意することができます。

ユースケースの実施に必要なデータを検討し、必要なデータのみにアクセスする権限をリクエストします。アプリケーションの範囲を大きく超える権限をリクエストすると、データの使用方法におけるユーザーの信頼を失う可能性があります。たとえば、個人向けの財務管理アプリケーションや融資商品を構築する場合は、transactions データをリクエストします。アカウントの乗っ取りなどの不正利用を減らす場合は、ownership の詳細をリクエストします。

ユーザーがアカウントを認証した後に権限を拡張するには、新しい Financial Connections Session を作成し、permissions パラメーターに新しい値を指定する必要があります。ユーザーは認証フローを再度完了する必要があり、そこでアクセスの権限をリクエストした追加データを確認し、データの共有に同意します。

オプションの prefetch パラメーター は、ユーザーが口座を連結した直後に取得するデータを制御します。特定の種類のデータが常に必要である場合は、このオプションを使用します。これにより、データの更新を開始するために追加の API コールを実行する必要がなくなります。

ACH ダイレクトデビットによる決済を受け付けるためのオプションを保持するには、payment_method 権限をリクエストします。

返された client_secret を Stripe.js で使用して、ユーザーが口座を関連付けられるようにします。client_secret により、クライアント側の Stripe SDK は Financial Connections Session を変更できます。これは、保存したり、ログに記録したり、URL に埋め込んだり、当該エンドユーザー以外の人に公開したりしないでください。client secret が含まれるすべてのページで TLS を有効化するのを忘れないでください。

口座を収集するには、collectFinancialConnectionsAccounts を使用します。

const stripe = new Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx')
const financialConnectionsSessionResult = await stripe.collectFinancialConnectionsAccounts({
  clientSecret: "{{SESSION_CLIENT_SECRET}}",
});

このメソッドにより、認証フローが読み込まれます。これは、ユーザーが金融口座を貴社と Stripe に関連付けできるようにするクライアント側の Stripe.js UI です。

stripe.collectFinancialConnectionsAccounts の戻り値は Promise です。ユーザーが認証フローを完了すると、Promise は、連結アカウントのリストを含むオブジェクトで解決されます。

{
  "financialConnectionsSession": {
    "id": "fcsess_123",
    "accounts": [
      {
        "id": "fca_456",
        "object": "financial_connections.account",
        "category": "Checking",
        "display_name": "Premium Checking",
        "institution_name": "Test Bank",
        "last4": "4242"
      }
    ]
  }
}

ユーザーが口座を関連付けないか、認証フローを途中で終了する場合、レスポンスに空の accounts 配列が含まれます。

認証フローが正常に完了すると、連結アカウントごとに 1 つの financial_connections.account.created Webhook も送信されます。

ユーザーが認証フローを正常に完了したら、Financial Connections Session の permissions パラメーターで指定した口座データのアクセスや更新を行います。

ユーザーのデータのプライバシーを保護するために、アクセスできる口座データは、permissions パラメーターで指定したデータに制限されています。

口座データの取得を開始するには、残高、所有権、取引のガイドをご覧ください。