Financial Connections アカウントの所有権情報にアクセスする
ユーザーの許可を得て口座の所有権情報にアクセスする方法をご紹介します。
Financial Connections API を使用すると、Financial Connections アカウントの所有権の詳細を取得できます。所有権データは、ユーザ登録時やリスク評価時の不正利用リスクの軽減など、さまざまな用途に利用できます。
はじめに
You must have a completed Financial Connections registration to access ownership in live mode. Visit your Dashboard settings to check the state of your registration or begin the registration process. Financial Connections test data is always available.
顧客を作成するRecommendedServer-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_ フィールドを確認します。
所有権の更新が完了すると、Stripe は ownership_refresh.next_refresh_available_at フィールドを使用して将来の更新の提供状況を設定します。新しい所有権の更新を開始する前にこのフィールドを調べて、更新が現在利用可能かどうかを確認してください。値が null のとき (更新が保留中か口座が非アクティブの場合は常にこの値) または現在時間が next_ タイムスタンプより前のときに更新しようとすると、更新は開始されません。
プライベートプレビュー
In the unlikely event that a refresh fails, the error field on the refresh hash is a preview feature that provides the cause of the failure and recommended next steps. If you’d like to use it, email us for access.
口座の所有権データを取得するサーバー側
所有権の更新が完了したら、 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 は、金融機関から提供された所有権情報を返しますが、所有権情報の提供状況はさまざまです。銀行から提供されたすべてのフィールドと所有者が返されます。所有権の詳細には、口座所有者の名前、住所、メールアドレス、電話番号が含まれる場合があります。
プライベートプレビュー
Ownership Match API はプレビュー版の機能であり、入力済みの所有者情報と比較して Financial Connections の所有権データを使用して一致スコアを返します。ビジネスはこのデータを使用して、ACH 支払いの受け付け時や資金の入金時に、不正利用者やアカウントの乗っ取りにさらされるリスクを減らせます。このプレビュー版機能のご利用をご希望の場合は、メール usでご連絡ください。