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

ユーザーの許可を得て口座の所有権情報にアクセスする方法をご紹介します。

Financial Connections API を使用すると、Financial Connections アカウントの所有権の詳細を取得できます。所有権データは、ユーザ登録時やリスク評価時の不正利用リスクの軽減など、さまざまな用途に利用できます。

はじめに

本番環境で ownership にアクセスするには、Financial Connections 登録が完了している必要があります。ダッシュボードの設定を調べて登録状態を確認するか、登録プロセスを開始してください。テスト環境の Financial Connections データはいつでも利用可能です。

顧客を作成する
Recommended
Server-side

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

口座の所有権データへのアクセス権をリクエストする
サーバー側

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

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

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

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

所有権の更新を開始する
サーバー側

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

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

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

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

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

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

注

更新は非アクティブなアカウントでは実行できません。

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

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 タイムスタンプより前のときに更新しようとすると、更新は開始されません。

ベータ

まれですが、更新が失敗した場合は、更新ハッシュの error フィールドを確認してください。このフィールドは、失敗の原因と推奨される次の手順を示すベータ機能です。ご利用をご希望の場合は、メールでお問い合わせください。

口座の所有権データを取得する
サーバー側

所有権の更新が完了したら、 API から Financial Connections アカウントを取得し、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 は、金融機関から提供された所有権情報を返しますが、所有権情報の提供状況はさまざまです。銀行から提供されたすべてのフィールドと所有者が返されます。所有権の詳細には、口座所有者の名前、住所、メールアドレス、電話番号が含まれる場合があります。