# Financial Connections アカウントの所有権情報にアクセスする ユーザーの許可を得て口座の所有権情報にアクセスする方法をご紹介します。 Financial Connections API を使用すると、[Financial Connections アカウント](https://docs.stripe.com/api/financial_connections/accounts/object.md)の所有権の詳細を取得できます。オーナーデータは、ユーザー登録時やリスク評価時の不正利用リスクの軽減など、さまざまな用途に利用できます。 ## Before you begin 本番環境で ownership にアクセスするには、Financial Connections の登録を完了している必要があります。[ダッシュボードの設定](https://dashboard.stripe.com/settings/financial-connections)に移動して登録状況を確認するか、登録プロセスを開始してください。Financial Connections のテストデータはいつでも利用できます。 ## 顧客を作成する [Recommended] [Server-side] ユーザーを表すメールアドレスと電話番号を含めて*顧客* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments)を作成し、その顧客を決済に関連付けることをお勧めします。`Customer` オブジェクトを関連付けることで、後で[以前に関連付けられた口座](https://docs.stripe.com/api/financial_connections/accounts/list.md)を一覧表示できます。`Customer` オブジェクトにメールアドレスと電話番号を入力すると、ユーザーがリピートの[Link](https://support.stripe.com/questions/link-for-financial-connections-support-for-businesses)ユーザーかどうかに応じて、Financial Connections がサインインまたはサインアップを簡素化し、認証フローを改善できます。 ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d email={{CUSTOMER_EMAIL}} \ -d phone={{CUSTOMER_PHONE}} ``` ## 口座の所有権データへのアクセス権をリクエストする [サーバー側] 所有権データにアクセスするには、アカウントを収集する必要があります。Financial Connections アカウントの収集方法について、詳細はご自身のユースケースに最も適した導入ガイドをご覧ください ([決済の受け付け](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md)、[Connect での入金の円滑化](https://docs.stripe.com/financial-connections/connect-payouts.md)、[データを利用するその他の商品の構築](https://docs.stripe.com/financial-connections/other-data-powered-products.md)など)。 [カスタムアカウントの Connect アカウント登録](https://docs.stripe.com/connect/payouts-bank-accounts.md?bank-account-collection-integration=prebuilt-web-form) を使用して Financial Connections アカウントを収集する場合は、アクセスしたいデータを[ダッシュボード](https://dashboard.stripe.com/settings/connect/custom)で設定します。 API 導入を使用して口座を収集する場合は、アクセスする必要があるデータを [permissions](https://docs.stripe.com/financial-connections/fundamentals.md#data-permissions) パラメーターで指定します。ユーザーは[認証フロー](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow)で、一連のリクエスト対象のデータ権限を表示できます。Financial Connections アカウントはさまざまな導入パスで収集できますが、パラメーターの指定方法は API によって若干異なります。 インテントを作成する前に、ダッシュボードで決済手段として[アメリカの銀行口座を有効化](https://dashboard.stripe.com/settings/payment_methods)してください。 #### Setup Intents ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "automatic_payment_methods[enabled]=true" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=ownership" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" ``` #### Payment Intents ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=20000 \ -d currency=usd \ -d "customer={{CUSTOMER_ID}}" \ -d "automatic_payment_methods[enabled]=true" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=ownership" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" ``` #### Sessions ```curl curl https://api.stripe.com/v1/financial_connections/sessions \ -u "<>:" \ -d "account_holder[type]=customer" \ -d "account_holder[customer]={{CUSTOMER_ID}}" \ -d "permissions[]=ownership" ``` #### Checkout ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=ownership" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" ``` #### 請求書 ```curl curl https://api.stripe.com/v1/invoices \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -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" ``` #### サブスクリプション ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d customer={{CUSTOMER_ID}} \ -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" ``` 特定の支払い API に対して動的な支払い方法を使用するときは、リクエストされた権限をダッシュボードで設定することもできます。[Financial Connections アカウントでその他の口座データにアクセスする](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md?dashboard-or-api=dashboard#access)方法をご覧ください。 ## 所有権の更新を開始する [サーバー側] Financial Connections データの取得はすべて非同期で行われます。所有権の更新を開始して、完了を待ってから結果を取得します。所有権の更新は、`prefetch` API パラメーターを使用するか、[Refresh API](https://docs.stripe.com/api/financial_connections/accounts/refresh.md) を使用して開始できます。 ### 所有権データをプリフェッチする 口座を収集する「前に」、口座の所有権の詳細をプリフェッチするかどうかを指定します。これにより、ユーザーが[認証フロー](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow) で口座を連結するとすぐに、更新プロセスが開始されます。関連付けられたすべての関連付けられた口座の所有権データが必要な場合に `prefetch` を設定すると、遅延を最小限に抑えて受け取ることができます。 `prefetch` パラメーターは、 Financial Connectionsをサポートするすべての API で使用できます。 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "automatic_payment_methods[enabled]=true" \ -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](https://docs.stripe.com/api/financial_connections/accounts/refresh.md) を使用すると、口座の収集「後」にオンデマンドで所有権の更新を開始し、特定の口座の所有権情報を都合の良いときに取得できるため、判断を先送りできます。口座所有権データは変更されることがありますが、一般に[残高](https://docs.stripe.com/financial-connections/balances.md)や[取引](https://docs.stripe.com/financial-connections/transactions.md)のデータほど頻繁に変更されることはありません。 Financial Connections アカウント ID を使用して更新を開始します。決済フローを使用して実装する場合は、[関連付けられている支払い方法](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md#finding-the-financial-connections-account-id)でアカウント ID を見つけます。Financial Connections Session を使用するときは、[該当セッション](https://docs.stripe.com/financial-connections/other-data-powered-products.md?platform=web#collect-an-account)から ID を取得します。 ```curl curl https://api.stripe.com/v1/financial_connections/accounts/{{FINANCIALCONNECTIONSACCOUNT_ID}}/refresh \ -u "<>:" \ -d "features[]=ownership" ``` > 更新は非アクティブなアカウントでは実行できません。 ### 所有権の更新の完了を待つ Financial Connections アカウントの [ownership_refresh](https://docs.stripe.com/api/financial_connections/accounts/object.md#financial_connections_account_object-ownership_refresh) フィールドは、所有権の更新ステータスを表します。`ownership` 権限をリクエストして更新を開始するまで、このフィールドは `null` になります。所有権の更新を開始すると、ステータスは `pending` に移行し、完了すると `succeeded` または `failed` になります。所有権の更新が完了すると、Stripe は [financial_connections.account.refreshed_ownership](https://docs.stripe.com/api/events/types.md#event_types-financial_connections.account.refreshed_ownership) イベントを送信します。所有権の更新が成功したことを確認するには、Webhook の処理中に `ownership_refresh.status` フィールドを確認します。 所有権の更新フロー (See full diagram at https://docs.stripe.com/financial-connections/ownership) ```text [ownership_refresh: null] -- プリフェッチ --> [ownership_refresh.status: pending] [ownership_refresh: null] -- Refresh API --> [ownership_refresh.status: pending] [ownership_refresh.status: pending] -- 成功 --> [ownership_refresh.status: succeeded] [ownership_refresh.status: pending] -- 失敗 --> [ownership_refresh.status: failed] [ownership_refresh.status: succeeded] -- 送信される Webhook --> [financial_connections.account.refreshed_ownership] [ownership_refresh.status: failed] -- 送信される Webhook --> [financial_connections.account.refreshed_ownership] ``` 所有権の更新が完了すると、Stripe は [ownership_refresh.next_refresh_available_at](https://docs.stripe.com/api/financial_connections/accounts/object.md#financial_connections_account_object-ownership_refresh-next_refresh_available_at) フィールドを使用して将来の更新の提供状況を設定します。新しい所有権の更新を開始する前にこのフィールドを調べて、更新が現在利用可能かどうかを確認してください。値が `null` のとき (更新が保留中か口座が非アクティブの場合は常にこの値) または現在時間が `next_refresh_available_at` タイムスタンプより前のときに更新しようとすると、更新は開始されません。 > まれですが、更新に失敗した場合は、プレビュー版の機能である更新ハッシュの `error` フィールドに、失敗の原因と推奨される次の手順が示されます。ご利用になりたい場合は、[メールでお問い合わせください](mailto:financial-connections-beta+refresh-error@stripe.com)。 ## 口座の所有権データを取得する [サーバー側] 所有権の更新が完了したら、 API から Financial Connections アカウントを取得し、[ownership](https://docs.stripe.com/api/financial_connections/accounts/object.md#financial_connections_account_object-ownership) フィールドを展開して所有権の詳細を表示します。 ```curl curl -G https://api.stripe.com/v1/financial_connections/accounts/{{FINANCIALCONNECTIONSACCOUNT_ID}} \ -u "<>:" \ -d "expand[]=ownership" ``` これにより Financial Connections アカウントが返され、その所有権フィールドが展開されて口座の所有者が一覧表示されます。 ```json { "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](mailto:financial-connections-beta+ownership-match@stripe.com)でご連絡ください。