# Financial Connections で銀行口座の所有権を確認する Ownership Match API を使用して、所有権データの一致スコアをリクエストします。 [Ownership Match API](https://docs.stripe.com/api/financial_connections/ownership_match.md) は、ユーザーが特定の銀行口座を所有していることを確認するのに役立ちます。Financial Connections の所有権データを入力済みの所有者情報を比較して、一致スコアを計算します。 ## Before you begin 本番環境で ownership にアクセスするには、Financial Connections の登録を完了している必要があります。[ダッシュボードの設定](https://dashboard.stripe.com/settings/financial-connections)に移動して登録状況を確認するか、登録プロセスを開始してください。Financial Connections のテストデータはいつでも利用できます。 Ownership Match にアクセスするには、各 API リクエストで [API バージョンとベータヘッダー](https://docs.stripe.com/sdks/set-version.md)を `financial_connections_ownership_match_api_preview=v1` に設定する必要があります。 ## 口座の所有権データへのアクセスをリクエストする [サーバー側] - [Financial Connections アカウントの所有権にアクセスする](https://docs.stripe.com/financial-connections/ownership.md) 所有権データにアクセスするには、[Financial Connections アカウントを収集](https://docs.stripe.com/financial-connections/ownership.md#request-account-ownership)する必要があります。 アクセスする必要がある [data permissions](https://docs.stripe.com/financial-connections/fundamentals.md#data-permissions) を、API の `permissions` パラメーターで指定します。Ownership Match には `ownership` 権限が必要です。 ユーザーは、[認証フロー](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow)でリクエストしたデータ権限を確認できます。 ユーザーが認証フローで口座を連結したらすぐに、[プリフェッチ](https://docs.stripe.com/financial-connections/ownership.md#prefetch-ownership-data)を使用して所有権の更新を開始することをお勧めします。 所有権データが利用可能になると、Stripe は [Financial Connections Webhook](https://docs.stripe.com/financial-connections/webhooks.md) を送信します。 ## Ownership Match API を呼び出す [サーバー側] 次のいずれかの方法で所有権データを API に渡すことができます。 - Stripe が比較できるよう Customer オブジェクトを作成する - 口座名義人のタイプが Customer である Financial Connections アカウントを収集します - `owner_information` パラメーターを使用してデータを送信する Ownership Match には、最大 4 つの入力フィールドを使用できます。そのうちの 1 つは次のリストから選ぶ必要があります。 - 氏名 - メールアドレス - **電話番号**: 海外の番号の場合は、プラス記号 (`+`) と国コードを含めます - **住所**： 2 行目を除くすべての住所フィールドが必要です > すべての所有権フィールドを含めると、スコアの精度が向上します。たとえば、各フィールドの一致スコアを重み付けして、リスクモデリングで使用できます。 ### Customer オブジェクトを作成する (Recommended) ユーザーを表す *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) を作成することをお勧めします。一致させるのに利用可能なすべてのデータを含めます。 Stripe がデータを読み込んで一致させるため、厳密には必要でないときに機密性の高い顧客データを処理する必要がありません。 たとえば、[Checkout での ACH 決済](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md)といった Stripe プロダクトを使用して、Customer と Financial Connections アカウントの両方を収集できます。その後、所有権の一致をリクエストし、顧客の所有権データを参照することなく、また PCI 準拠の責任が生じ得ることなく、一致結果に基づいてリスク決定を下すことができます。 ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d "name=Jenny Rosen" \ --data-urlencode "email=jennyrosen@example.com" \ --data-urlencode "phone=+1 212-555-5555" \ -d "address[line1]=354 Oyster Point Blvd" \ -d "address[city]=South San Francisco" \ -d "address[postal_code]=94080" \ -d "address[state]=CA" \ -d "address[country]=US" ``` これにより、Ownership Match で使用可能な所有権の詳細を持つ Customer が返されます。 ```json { "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 アカウントと照合します。 ```curl curl https://api.stripe.com/v1/financial_connections/ownership_match \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview; financial_connections_ownership_match_api_preview=v1" \ -d financial_connections_account=fca_1MwVK82eZvKYlo2Cjw8FMxXf \ -d type=customer \ -d customer=cus_NffrFeUfNV2Hib ``` ### 口座名義人のタイプが Customer である Financial Connections アカウントを収集します Financial Connections Session の作成時に `customer` を既存の顧客 ID に設定し、アカウント所有者を `customer` に設定することで、関連付けられた顧客を持つ Financial Connections アカウントを収集できます。 #### Setup Intents ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d customer=cus_NffrFeUfNV2Hib \ -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" \ -d "payment_method_options[us_bank_account][financial_connections][prefetch][]=ownership" ``` #### Payment Intents ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=20000 \ -d currency=usd \ -d customer=cus_NffrFeUfNV2Hib \ -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" \ -d "payment_method_options[us_bank_account][financial_connections][prefetch][]=ownership" ``` #### 年次イベント ```curl curl https://api.stripe.com/v1/financial_connections/sessions \ -u "<>:" \ -d "account_holder[type]=customer" \ -d "account_holder[customer]=cus_NffrFeUfNV2Hib" \ -d "permissions[]=ownership" \ -d "prefetch[]=ownership" ``` #### 決済 ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d customer=cus_NffrFeUfNV2Hib \ -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" \ -d "payment_method_options[us_bank_account][financial_connections][prefetch][]=ownership" ``` #### 請求書 ```curl curl https://api.stripe.com/v1/invoices \ -u "<>:" \ -d customer=cus_NffrFeUfNV2Hib \ -d "payment_settings[payment_method_types][]=us_bank_account" \ -d "payment_settings[payment_method_options][us_bank_account][financial_connections][permissions][]=ownership" \ -d "payment_settings[payment_method_options][us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_settings[payment_method_options][us_bank_account][financial_connections][prefetch][]=ownership" ``` #### サブスクリプション ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d customer=cus_NffrFeUfNV2Hib \ -d "payment_settings[payment_method_types][]=us_bank_account" \ -d "payment_settings[payment_method_options][us_bank_account][financial_connections][permissions][]=ownership" \ -d "payment_settings[payment_method_options][us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_settings[payment_method_options][us_bank_account][financial_connections][prefetch][]=ownership" ``` これにより、必要な `ownership` 権限と関連付けられた Customer を持つ Financial Connections アカウントが作成されます。所有権のプリフェッチまたは更新が成功すると、`ownership` が拡張されたときに関連付けられた Financial Connections 所有権データを含め、アカウントが返されます。 ```json { "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 の所有権データを、関連付けられている口座名義人の顧客データと照合できます。 ```curl curl https://api.stripe.com/v1/financial_connections/ownership_match \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview; financial_connections_ownership_match_api_preview=v1" \ -d financial_connections_account=fca_1MwVK82eZvKYlo2Cjw8FMxXf ``` ### Owner Information パラメーターを使用してデータを送信する Customer を通じて所有権データを収集しないことを選択した場合は、`owner_information` パラメーターを使用して、ユーザー提供の所有権データを API に直接渡すこともできます。 ```json { "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 アカウントと照合します。 ```curl curl https://api.stripe.com/v1/financial_connections/ownership_match \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview; financial_connections_ownership_match_api_preview=v1" \ -d financial_connections_account=fca_1MwVK82eZvKYlo2Cjw8FMxXf \ -d type=owner_information \ -d "owner_information[name]=Jenny Rosen" \ --data-urlencode "owner_information[email]=jennyrosen@example.com" \ --data-urlencode "owner_information[phone]=+1 212-555-5555" \ -d "owner_information[address][line1]=354 Oyster Point Blvd" \ -d "owner_information[address][line2]=" \ -d "owner_information[address][city]=South San Francisco" \ -d "owner_information[address][state]=CA" \ -d "owner_information[address][postal_code]=94080" \ -d "owner_information[address][country]=US" ``` ## 一致の結果に基づいて判定を行う [サーバー側] Ownership Match API は、入力した各入力フィールドに対して 0 から 100 までの一致スコアを返します。この一致スコアを、例に示すように、独自のリスクロジックとモデリングにフィードできます。たとえば、支払いを続行するスコアのしきい値や、続行する前に追加で本人確認 (身分証明書のアップロードなど) を要求するスコアのしきい値を設定できます。 リスク許容度と顧客データから得られるその他のリスクシグナルに応じて、ロジックを調整します。具体的には、支払いの継続やアカウントへの入金許可といったアクションを進めるには、完全一致または強一致を要求するなどです。 ```javascript 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」、および次のアドレスと比較した一致スコアのサンプル: ```json { "line1": "354 Oyster Point Blvd", "line2": "Fl 1", "city": "South San Francisco", "state": "CA", "postal_code": "94080", "country": "US" } ``` | スコア | 解釈 | 名前の例 | メールアドレスの例 | 住所の例 | | ----- | --------------------------- | ---------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 100 | 完全一致 | 「ジェニー・ジェーン・ローゼン」 | 「jennyrosen@example.com」 | ```json { "line1": "354 Oyster Point Blvd.", "line2": "Fl. 1", "city": "South San Francisco", "state": "CA", "postal_code": "94080", "country": "US" } ``` | | 85-99 | 非常に強い一致 (わずかな文字ずれ、など) | 「ジュニー・ジェーン・ローゼン」 | 「jenny.rosen@example.com」 | ```json { "line1": "354 Oyster Point Blvd.", "line2": null, "city": "South San Francisco", "state": "CA", "postal_code": "94080", "country": "US" } ``` | | 70-84 | 強い一致 (大半が一致、など) | 「ジェニー・ローゼン」 | 「jennyrosen12345@example.com」 | ```json { "line1": "354 Oyster Point", "line2": "Fl. 10", "city": "San Francisco", "state": "CA", "postal_code": "94080", "country": "US" } ``` | | 60-69 | 一致する可能性あり (一部一致、ニックネーム、など) | 「ジェニファー・ローゼン」 | 「jennyrosen@test.com」 | ```json { "line1": "354 OP Blvd.", "line2": null, "city": "South SF", "state": "CA", "postal_code": "94080", "country": "US" } ``` | | 30-59 | 弱い一致 (同居人または類似フィールドの可能性、など) | 「マーク・ローゼン」 | 「marksmith@example.com」 | ```json { "line1": "510 Townsend St.", "line2": null, "city": "San Francisco", "state": "CA", "postal_code": "94103", "country": "US" } ``` | | 0-29 | 一致しない、または一致する可能性が低い | 「マーク・スミス」 | 「marksmith@test.com」 | ```json { "line1": "1 University Ave.", "line2": "Fl. 10", "city": "Toronto", "state": "ON", "postal_code": "M5J 2P1", "country": "CA" } ``` | #### 電話番号 電話番号「+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 も返します。 ```json { "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 } } } ```