Financial Connections で銀行口座の所有権を確認する非公開プレビュー
Ownership Match API を使用して、所有権データの一致スコアをリクエストします。
Ownership Match API は、ユーザーが特定の銀行口座を所有していることを確認するのに役立ちます。Financial Connections の所有権データを入力済みの所有者情報を比較して、一致スコアを計算します。
はじめに
本番環境で ownership にアクセスするには、Financial Connections の登録を完了している必要があります。ダッシュボードの設定に移動して登録状況を確認するか、登録プロセスを開始してください。Financial Connections のテストデータはいつでも利用できます。
Ownership Match にアクセスするには、各APIリクエストでAPIバージョンとベータヘッダー を financial_に設定する必要があります。
口座の所有権データへのアクセスをリクエストするサーバー側
所有権データにアクセスするには、Financial Connections アカウントを収集する必要があります。
アクセスする必要がある data permissions を、API の permissions パラメーターで指定します。Ownership Match には ownership 権限が必要です。
ユーザーは、認証フローでリクエストしたデータ権限を確認できます。
ユーザーが認証フローで口座を連結したらすぐに、プリフェッチを使用して所有権の更新を開始することをお勧めします。
所有権データが利用可能になると、Stripe は Financial Connections Webhook を送信します。
Ownership Match API を呼び出すサーバー側
次のいずれかの方法で所有権データを API に渡すことができます。
- Stripe が比較できるよう Customer オブジェクトを作成する
- 口座名義人のタイプが Customer である Financial Connections アカウントを収集します
owner_パラメーターを使用してデータを送信するinformation
Ownership Match には、最大 4 つの入力フィールドを使用できます。そのうちの 1 つは次のリストから選ぶ必要があります。
- 氏名
- メールアドレス
- 電話番号: 海外の番号の場合は、プラス記号 (
+) と国コードを含めます - 住所： 2 行目を除くすべての住所フィールドが必要です
注
すべての所有権フィールドを含めると、スコアの精度が向上します。たとえば、各フィールドの一致スコアを重み付けして、リスクモデリングで使用できます。
Customer オブジェクトを作成する 推奨
ユーザーを表す Customer を作成することをお勧めします。一致させるのに利用可能なすべてのデータを含めます。
Stripe がデータを読み込んで一致させるため、厳密には必要でないときに機密性の高い顧客データを処理する必要がありません。
たとえば、Checkout での ACH 決済といった Stripe プロダクトを使用して、Customer と Financial Connections アカウントの両方を収集できます。その後、所有権の一致をリクエストし、顧客の所有権データを参照することなく、また PCI 準拠の責任が生じ得ることなく、一致結果に基づいてリスク決定を下すことができます。
これにより、Ownership Match で使用可能な所有権の詳細を持つ Customer が返されます。
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", "created": 1651783000, "name": "Jenny Rosen", "address": { "line1": "354 Oyster Point Blvd", "line2": null, "city": "South San Francisco", "state": "CA", "postal_code": "94080", "country": "US" }, "email": "jennyrosen@example.com", "phone": "+1 212-555-5555", "livemode": false // ... }
API に Customer id を渡して、Financial Connections アカウントと照合します。
口座名義人のタイプが Customer である Financial Connections アカウントを収集します
Financial Connections Session の作成時に customer を既存の顧客 ID に設定し、アカウント所有者を customer に設定することで、関連付けられた顧客を持つ Financial Connections アカウントを収集できます。
これにより、必要な ownership 権限と関連付けられた Customer を持つ Financial Connections アカウントが作成されます。所有権のプリフェッチまたは更新が成功すると、ownership が拡張されたときに関連付けられた Financial Connections 所有権データを含め、アカウントが返されます。
{ "id": "fca_1MwVK82eZvKYlo2Cjw8FMxXf", "object": "financial_connections.account", "created": 1651783222, "account_holder": { "customer": "cus_NffrFeUfNV2Hib", "type": "customer" }, "ownership": { "id": "fcaowns_1NtI9uBHO5VeT9SUSRe21lqt", "object": "financial_connections.account_ownership", "created": 1651784999, "owners": { "object": "list", "data": [ { "name": "Jennifer Rosen", "email": "jennyrosen@test.com", "phone": null, "ownership": "fcaowns_1NtI9uBHO5VeT9SUSRe21lqt", "raw_address": "354 Oyster Point Blvd South San Francisco, CA 94080 USA", "refreshed_at": 1651784999 } ], "has_more": false, "url": "/v1/financial_connections/accounts/fca_zbyrdjTrwcYZJZc6WBs6GPid/owners?ownership=fcaowns_1NtI9uBHO5VeT9SUSRe21lqt" } }, "ownership_refresh": { "status": "succeeded", "last_attempted_at": 1651784999, "next_refresh_available_at": 1651785000 }, "permissions": ["ownership", "payment_method"], "prefetch": ["ownership"] // ... }
入力 type を指定せずに Financial Connections アカウントの id を渡すことで、Financial Connections の所有権データを、関連付けられている口座名義人の顧客データと照合できます。
Owner Information パラメーターを使用してデータを送信する
Customer を通じて所有権データを収集しないことを選択した場合は、owner_ パラメーターを使用して、ユーザー提供の所有権データを API に直接渡すこともできます。
{ "owner_information": { "name": "Jenny Rosen", "email": "jennyrosen@example.com", "phone": "+1 212-555-5555", "address": { "line1": "354 Oyster Point Blvd", "line2": null, "city": "South San Francisco", "state": "CA", "postal_code": "94080", "country": "US" } } }
API に所有者情報を渡して、Financial Connections アカウントと照合します。
一致の結果に基づいて判定を行うサーバー側
Ownership Match API は、入力した各入力フィールドに対して 0 から 100 までの一致スコアを返します。この一致スコアを、例に示すように、独自のリスクロジックとモデリングにフィードできます。たとえば、支払いを続行するスコアのしきい値や、続行する前に追加で本人確認 (身分証明書のアップロードなど) を要求するスコアのしきい値を設定できます。
リスク許容度と顧客データから得られるその他のリスクシグナルに応じて、ロジックを調整します。具体的には、支払いの継続やアカウントへの入金許可といったアクションを進めるには、完全一致または強一致を要求するなどです。
function makeRiskDecision(matchResult: Stripe.FinancialConnections.OwnershipMatch) { const nameScore = matchResult.results.name?.match_score? || 0; const addressScore = matchResult.results.address?.match_score? || 0; const emailScore = matchResult.results.email?.match_score? || 0; const phoneScore = matchResult.results.phone?.match_score? || 0; const overallScore = (nameScore + addressScore + emailScore + emailScore) / 4 if (overallScore >= 70) { proceedWithPayment(); } else if (overallScore >= 60) { stepUpVerification(); } else { cancelPayment(); } }
スコアの解釈例
氏名、メールアドレス、住所
名前「Jenny Jane Rosen」、メールアドレス「jennyrosen@example.com」、および次のアドレスと比較した一致スコアのサンプル:
{ "line1": "354 Oyster Point Blvd", "line2": "Fl 1", "city": "South San Francisco", "state": "CA", "postal_code": "94080", "country": "US" }
| スコア | 解釈 | 名前の例 | メールアドレスの例 | 住所の例 |
|---|---|---|---|---|
| 100 | 完全一致 | 「ジェニー・ジェーン・ローゼン」 | 「jennyrosen@example.com」 |
|
| 85-99 | 非常に強い一致 (わずかな文字ずれ、など) | 「ジュニー・ジェーン・ローゼン」 | 「jenny.rosen@example.com」 |
|
| 70-84 | 強い一致 (大半が一致、など) | 「ジェニー・ローゼン」 | 「jennyrosen12345@example.com」 |
|
| 60-69 | 一致する可能性あり (一部一致、ニックネーム、など) | 「ジェニファー・ローゼン」 | 「jennyrosen@test.com」 |
|
| 30-59 | 弱い一致 (同居人または類似フィールドの可能性、など) | 「マーク・ローゼン」 | 「marksmith@example.com」 |
|
| 0-29 | 一致しない、または一致する可能性が低い | 「マーク・スミス」 | 「marksmith@test.com」 |
|
電話番号
電話番号「+1 212-555-5555」と比較した電話番号の一致スコアのサンプル。
注
電話番号では細かいばらつきは少ないため、電話サンプルの解釈スコアの範囲はより広くなります。
| スコア | 解釈 | 例 |
|---|---|---|
| 100 | 完全一致 | 「+12125555555」、「(212) 555-5555」 |
| 70-99 | 一致する可能性あり (数字がずれている、番号が欠落している、など) | 「212 555 5559」、「212 555 555」 |
| 50-69 | 弱い一致 (市外局番以外はすべて同じ、など) | 「347 555 5555」 |
| 20-49 | 一致する可能性が低い (市外局番のみが同じ、など) | 「212 999 9999」 |
| 0-19 | 一致しません | 「347 999 9999」 |
サンプルレスポンス
次の API レスポンスの例に示すように、Ownership Match API は、一致した所有者情報と所有権 ID も返します。
{ "id": "fcom_1NtI9uBHO5VeT9SUKLJU5suZ", "object": "financial_connections.ownership_match", "created": 1745858181, "financial_connections_account": "fca_1MwVK82eZvKYlo2Cjw8FMxXf", "type": "customer", "owner_information": { "name": "Jenny Rosen", "address": { "line1": "354 Oyster Point Blvd", "line2": null, "city": "South San Francisco", "state": "CA", "postal_code": "94080", "country": "US" }, "email": "jennyrosen@example.com", "phone": "+1 212-555-5555" }, "customer": "cus_NffrFeUfNV2Hib", "ownership": "fcaowns_1NtI9uBHO5VeT9SUSRe21lqt", "results": { "name": { "match_score": 85, "missing_data": false }, "address": { "match_score": 100, "missing_data": false }, "email": { "match_score": 65, "missing_data": false }, "phone": { "match_score": null, "missing_data": true } } }