Financial Connections アカウントの所有権情報にアクセスする

Customer は、ユーザーを表すメールアドレスを含めて作成し、支払いに関連付けられるようにすることをお勧めします。Customer オブジェクトを関連付けることで、後ですでに関連付けられたことがある口座を一覧表示できます。Customer オブジェクトにメールアドレスを入力すると、Financial Connections では Link のリピートユーザーであるかどうかに応じてユーザーのサインインまたは登録を効率化することで、認証フローを改善できます。

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

所有権データにアクセスするには、アカウントを収集する必要があります。Financial Connections アカウントの収集方法について、詳細はご自身のユースケースに最も適した導入ガイドをご覧ください (決済の受け付け、Connect での入金の円滑化、データを利用するその他の商品の構築など)。

カスタムアカウントの Connect アカウント登録 を使用して Financial Connections アカウントを収集する場合は、アクセスしたいデータをダッシュボードで設定します。

API 導入を使用して口座を収集する場合は、アクセスする必要があるデータを permissions パラメーターで指定します。ユーザーは認証フローで、一連のリクエスト対象のデータ権限を表示できます。Financial Connections アカウントはさまざまな導入パスで収集できますが、パラメーターの指定方法は API によって若干異なります。

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "payment_method_types[]"=us_bank_account \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=ownership \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=payment_method

特定の支払い API に対して動的な支払い方法を使用するときは、リクエストされた権限をダッシュボードで設定することもできます。Financial Connections アカウントでその他の口座データにアクセスする方法をご覧ください。

Financial Connections データの取得はすべて非同期で行われます。所有権の更新を開始して、完了を待ってから結果を取得します。所有権の更新は、prefetch API パラメーターを使用するか、Refresh API を使用して開始できます。

所有権データをプリフェッチする

口座を収集する「前に」、口座の所有権の詳細をプリフェッチするかどうかを指定します。これにより、ユーザーが認証フロー で口座を連結するとすぐに、更新プロセスが開始されます。関連付けられたすべての関連付けられた口座の所有権データが必要な場合に prefetch を設定すると、遅延を最小限に抑えて受け取ることができます。 prefetch パラメーターは、 Financial Connectionsをサポートするすべての API で使用できます。

curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}} \
  -d "payment_method_types[]"=us_bank_account \
  -d "payment_method_options[us_bank_account][financial_connections][prefetch][]"=ownership \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=payment_method \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=ownership

オンデマンド更新を開始する

Refresh API を使用すると、口座の収集「後」にオンデマンドで所有権の更新を開始し、特定の口座の所有権情報を都合の良いときに取得できるため、判断を先送りできます。口座所有権データは変更されることがありますが、一般に残高や取引のデータほど頻繁に変更されることはありません。

Financial Connections アカウント ID を使用して更新を開始します。決済フローを使用して実装する場合は、関連付けられている支払い方法でアカウント ID を見つけます。Financial Connections Session を使用するときは、該当セッションから ID を取得します。

curl https://api.stripe.com/v1/financial_connections/accounts/
{{ACCOUNT_ID}}
/refresh \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "features[]"=ownership

所有権の更新の完了を待つ

Financial Connections アカウントの ownership_refresh フィールドは、所有権の更新ステータスを表します。ownership 権限をリクエストして更新を開始するまで、このフィールドは null になります。所有権の更新を開始すると、ステータスは pending に移行し、完了すると succeeded または failed になります。所有権の更新が完了すると、Stripe は financial_connections.account.refreshed_ownership イベントを送信します。所有権の更新が成功したことを確認するには、Webhook の処理中に ownership_refresh.status フィールドを確認します。

所有権の更新が完了すると、Stripe は ownership_refresh.next_refresh_available_at フィールドを使用して将来の更新の提供状況を設定します。新しい所有権の更新を開始する前にこのフィールドを調べて、更新が現在利用可能かどうかを確認してください。値が null のとき (更新が保留中か口座が非アクティブの場合は常にこの値) または現在時間が next_refresh_available_at タイムスタンプより前のときに更新しようとすると、更新は開始されません。

所有権の更新が完了したら、 API から Financial Connections アカウントを取得し、ownership フィールドを展開して所有権の詳細を表示します。

curl -G https://api.stripe.com/v1/financial_connections/accounts/
{{ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "expand[]"=ownership

これにより Financial Connections アカウントが返され、その所有権フィールドが展開されて口座の所有者が一覧表示されます。

{
  "id": "fca_zbyrdjTrwcYZJZc6WBs6GPid",
  "object": "financial_connections.account",
  "ownership": {
    "id": "fcaowns_1MzTG4IG1CZuezXppfPbUpXb",
    "object": "financial_connections.account_ownership",
    "created": 1651784999,
    "owners": {
      "object": "list",
      "data": [
        {
          "name": "Jenny Rosen",
          "email": "jenny.rosen@example.com",
          "phone": "+1 555-555-5555",
          "ownership": "fcaowns_1MzTG4IG1CZuezXppfPbUpXb",
          "raw_address": "510 Townsend San Francisco, CA 94103",
          "refreshed_at": 1651784999
        }
      ],
      "has_more": false,
      "url": "/v1/financial_connections/accounts/fca_zbyrdjTrwcYZJZc6WBs6GPid/owners?ownership=fcaowns_1MzTG4IG1CZuezXppfPbUpXb"
    }
  },
  "ownership_refresh": {
    "status": "succeeded",
    "last_attempted_at": 1651784999,
    "next_refresh_available_at": 1651785000
  },
  // ...
}

Stripe は、金融機関から提供された所有権情報を返しますが、所有権情報の提供状況はさまざまです。銀行から提供されたすべてのフィールドと所有者が返されます。所有権の詳細には、口座所有者の名前、住所、メールアドレス、電話番号が含まれる場合があります。