# 連結アカウントの入金口座を管理する 連結アカウントの外部銀行口座とデビットカードを管理する方法をご紹介します。 *入金* (A payout is the transfer of funds to an external account, usually a bank account, in the form of a deposit)口座には、銀行口座かデビットカードのいずれかを使用できます。Stripe では、Connect アカウント登録のウェブフォームで外部口座の詳細を収集することをお勧めしています。こうすることで、以下のように利用することができます。 - 設計と開発の時間を節約する。 - 口座番号や金融番号などの機密データをサーバーに保存する必要がなくなる。 - 連結アカウントでアカウントの詳細を入力する際のフォーム検証を構築する必要がなくなります。 アメリカでは、連結アカウントが金融口座をお客様のビジネスに安全に関連付けることができるため、[Stripe Financial Connections](https://docs.stripe.com/financial-connections.md) の使用もお勧めしています。これには以下のようなメリットがあります。 - アカウントが口座番号と金融番号を見つけるためにプロセスを中断する必要がないようにすることで、アカウント登録の完了率を高めます。 - 口座番号と金融番号の手動入力に起因するエラーを排除することで、初回入金の失敗率を低減します。 - 口座番号や金融番号などの機密データをサーバーに保存する必要がなくなる。 - アカウントがカスタムのアカウント登録フォームにアカウントの詳細を入力する際に、フォーム検証を構築する必要がなくなります。 - (アカウント v1 のみ) アカウントが [Link](https://support.stripe.com/questions/link-for-financial-connections-support-for-businesses) に保存した銀行口座情報を再使用できるため、認証に必要な手順を少なくすることができます。Link を使用していずれかの Stripe ビジネスに口座情報を保存しているアカウントは、Financial Connections の次回使用時にアカウントの詳細をプラットフォームと共有できます。 - [balances](https://docs.stripe.com/financial-connections/balances.md)、[所有権データ](https://docs.stripe.com/financial-connections/ownership.md)、[取引](https://docs.stripe.com/financial-connections/transactions.md)などのアカウントの外部銀行口座に関する追加情報にアクセスします。外部の銀行口座保有者の名前や住所などの情報を確認することで、アカウント登録時の不正を減らすことができます。 [Link を有効にすると](https://dashboard.stripe.com/settings/connect/payouts/external_accounts)、Stripe が提供するホスト型および埋め込み型のアカウント登録では Financial Connections verification の料金は発生しません。それ以外の場合は、[標準の Financial Connections verification 料金](https://stripe.com/financial-connections#pricing)が適用されます。 連結アカウントに API によるアカウント登録を使用している場合は、アカウント登録フローのカスタムフォームを使用して入金口座の詳細を収集できます。 ### 外部アカウント収集のオプトアウト Custom アカウントなど、プラットフォームが要件収集を担当するアカウントの場合、アカウント登録時に外部アカウント情報を収集しないようにすることができます。これは、外部アカウント情報を収集する独自のアカウント登録フローを構築する場合などに実行できます。 埋め込み型のアカウント登録では、アカウントセッションの `external_account_collection` 機能を false に設定することで、[外部アカウント情報の収集を無効化](https://docs.stripe.com/connect/supported-embedded-components/account-onboarding.md?#external-account-collection)できます。または、ホスト型のアカウント登録では、[Connect 外部アカウントの設定](https://dashboard.stripe.com/settings/connect/payouts/external_accounts)に移動して、 **プラットフォームが要件の収集を担当するアカウント** で外部アカウント情報の収集を有効化または無効化できます。これはデフォルトでオフになっていることに注意してください。 ## 外部アカウントを収集する #### Stripe のホスト型または埋め込み型のアカウント登録 [Stripe が提供するホスト型および埋め込み型のユーザー登録](https://docs.stripe.com/connect/onboarding.md)は、テーマをカスタマイズできる Web フォームを使用して、連結アカウントのユーザー登録に必要な情報を収集します。銀行口座情報の収集には Financial Connections を利用できますが、デビットカード情報の収集には利用できません。 プラットフォームがマイナス残高を負担する連結アカウントの場合、[外部口座](https://dashboard.stripe.com/settings/connect/payouts/external_accounts)設定で外部口座の回収フローをカスタマイズできます。 **外部口座**設定では、次のことができます。 - **デビットカードの使用を許可しますか？** の下で選択して、デビットカードの収集を有効または無効にします。 - デビットカードなどの他の種類の外部口座を追加する前に、連結アカウントで少なくとも 1 件の銀行口座を追加する必要があることを要求します。この設定には、**1 件以上の銀行口座が必要ですか？**でアクセスできます。これは、[自動引き落とし](https://docs.stripe.com/connect/account-balances.md#automatically-debit-connected-accounts)のサポートを確保するのに役立ちます。 - 連結アカウントが特定の通貨で複数の外部口座を追加するかどうかを制御します。通貨ごとに外部口座は 5 件までという制限があります。**通通貨ごとに複数の外部口座を収集します**で、この設定にアクセスできます。 #### Stripe Financial Connections を使用する ### 利用可能な国 - US アメリカの Stripe プラットフォームは、Stripe が提供するホスト型または埋め込み型のアカウント登録内で、以下の手順に従って [Stripe Financial Connections](https://docs.stripe.com/financial-connections.md) を有効にできます。 1. [外部口座設定](https://dashboard.stripe.com/settings/connect/payouts/external_accounts) に移動します。ここで、オプションの Connect アカウント登録機能を管理できます。 1. 要件が変更された場合にプラットフォームがアカウント情報を収集する連結アカウントは、Stripe が提供するホスト型または埋め込み型のアカウント登録で外部口座詳細を収集できるようにする必要があります。**Custom アカウントの Stripe ホスティング登録** で、トグルをオンにして Stripe が外部口座情報を収集できるようにします。 1. **銀行口座情報をどのように収集しますか？** で、**Financial Connections** を選択します。 1. (オプション) 残高、所有権の詳細、取引など、Financial Connections で即座に確認された口座に関する追加データにアクセスするための権限をリクエストします。この追加情報をリクエストする選択をすると、Stripe Financial Connections に登録するように求められます。 外部口座情報の収集が有効になっている場合、アカウント登録フローでは、すべての連結アカウントに対して銀行口座の認証が求められます。 ![Stripe Financial Connections を使用して入金口座を収集する Connect アカウント登録フローの画像。](https://b.stripecdn.com/docs-statics-srv/assets/connect-custom-onboarding-financial-connections-onboarding.8937a023f6682c90bab8c0b39873909a.png) Stripe Financial Connections を使用して入金口座を収集する Connect アカウント登録フロー。 連結アカウントが Financial Connections を使用して銀行口座をすぐには確認できない場合、確認プロセスは自動的に手動入力に戻ります。 ![Stripe Financial Connections ダイアログを使用して手動入力で入金口座を収集する Connect アカウント登録フローのイメージ。](https://b.stripecdn.com/docs-statics-srv/assets/connect-custom-onboarding-financial-connections-manual-entry.930da1e01c9026b9014008d75958bc8c.png) Stripe Financial Connections ダイアログを使用して手動入力で入金口座を収集する Connect アカウント登録フロー。 アカウント登録後、指定した銀行口座が連結アカウントに自動的に関連付けられます。 ## Financial Connections アカウントに関するデータを取得する (サーバー側) 連結アカウントが Financial Connections アカウントを関連付けたかどうかを判断するには、その `Account` ID を使用して、関連付けられている Financial Connections アカウントを取得します。`Account` ID を `account_holder.account` として指定し、`Stripe-Account` ヘッダーにも指定します。 ```curl curl -G https://api.stripe.com/v1/financial_connections/accounts \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "account_holder[account]={{CONNECTEDACCOUNT_ID}}" ``` これにより、以下のような API レスポンスが返されます。 ```json { "object": "list", "data": [ { "id": "fca_zbyrdjTrwcYZJZc6WBs6GPid", "object": "financial_connections.account", "account_holder": { "account": "{{CONNECTED_ACCOUNT_ID}}", "type": "account" }, ... "supported_payment_method_types": [ "us_bank_account" ] } ... ] } ``` Financial Connectionsアカウントが表示された場合は、アカウント登録プロセスで、連結アカウントがそれらのアカウントを関連付けたことを示します。 `id` 値を使用すると、[外部口座設定](https://dashboard.stripe.com/settings/connect/payouts/external_accounts)で指定したデータへのアクセスや、データの更新を行うことができます。連結アカウントのデータのプライバシーを保護するため、アクセスできるのは指定したデータのみです。 口座データの取得を開始するには、[残高](https://docs.stripe.com/financial-connections/balances.md)、[所有権](https://docs.stripe.com/financial-connections/ownership.md)、[取引](https://docs.stripe.com/financial-connections/transactions.md) のガイドに従ってください。後続のすべての口座の取得リクエストと更新リクエストには、連結アカウントの ID を指定した `Stripe-Account` ヘッダーを必ず含めてください。 ```curl curl https://api.stripe.com/v1/financial_connections/accounts/fca_zbyrdjTrwcYZJZc6WBs6GPid/refresh \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "features[]=balance" ``` #### 銀行口座の詳細の手動入力を有効にする Stripe がアカウント登録フォーム内で連結アカウントから銀行口座の詳細を手動で収集できるようにするには、以下の手順を使用します。 1. Connect の設定を開き、Payouts > External Accounts に移動します。ここで Connect アカウント登録オプションを管理できます。 1. **銀行口座情報をどのように収集しますか？** で、銀行口座情報を手動で収集するオプションを選択します。 1. 要件が変更された場合にプラットフォームがアカウント情報を収集する連結アカウントは、Stripe が提供するホスト型または埋め込み型のアカウント登録で外部口座詳細を収集できるようにする必要があります。**プラットフォームが要件を収集する責任を持つアカウント** で、トグルをオンにして Stripe が外部口座情報を収集できるようにします。 ![フォームを使用して手動入力で入金口座を収集する Connect アカウント登録フローの画像。](https://b.stripecdn.com/docs-statics-srv/assets/connect-custom-onboarding-payout-manual-entry-form.6764993258659b2ad6517e0825181e49.png) フォームを使用して手動入力で入金口座を収集する Connect アカウント登録フロー。 銀行口座の詳細の形式は国ごとに若干異なります。フォームでは、営業している国に応じて適切なフィールドが自動的に表示されます。 #### カスタムフォームからのダイレクト API コール 要件が変更された場合にプラットフォームがアカウント情報を収集する連結アカウントは、カスタムフォームからダイレクト API コールを行うことで外部口座情報を収集できます。 #### Stripe Financial Connections を有効にする ### 利用可能な国 - US アメリカの Stripe プラットフォームは、カスタムのアカウント登録フォーム内で [Stripe Financial Connections](https://stripe.com/financial-connections) を有効にすることができます。フォーム内で Stripe Financial Connections を有効にすると、連結アカウントは、すぐに[認証フロー](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow)内で銀行口座を認証します。[Financial Connections に登録](https://dashboard.stripe.com/financial-connections/application)して、本番環境でのアクセスが承認されるようにします。 ### SetupIntent を作成する (サーバー側) サーバー側のエンドポイントを呼び出すボタンまたはリンクをユーザ登録フォームに挿入して、[SetupIntent](https://docs.stripe.com/api/setup_intents.md) を作成します。SetupIntent は、連結アカウントの銀行口座情報を収集する意図を表します。たとえば、ボタンには**銀行口座をリンク**と表示されます。 接続される各アカウントに対応するメールアドレス付きの Customer を作成することをおすすめします。Customer オブジェクトを関連付けておくと、後から[これまでにリンクされた外部アカウントを一覧表示](https://docs.stripe.com/api/financial_connections/accounts/list.md)できます。顧客の作成時にメールアドレスを指定すると、[Link](https://support.stripe.com/questions/link-for-financial-connections-support-for-businesses)を使って銀行口座情報を保存および再利用することで、Stripe を利用する各事業者間で少ないステップでアカウントに認証できるようになり、[Financial Connections 認証フロー](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow)を最適化できます。 連結アカウントの銀行口座情報を収集する SetupIntent を作成する際は、以下のパラメーターを設定します。 1. `customer` タイプを [Customer の ID](https://docs.stripe.com/api/customers/object.md#customer_object-id) に設定する 1. `payment_method_types` を `["us_bank_account"]` に設定する 1. `flow_directions` を `["outbound"]` に設定する 1. (オプション) ユースケースの実施に必要な追加データを検討し、そのデータにアクセスするための権限をリクエストします。たとえば、`payment_method_options[us_bank_account][financial_connections][permissions]` を `["payment_method", "ownership"]` に設定して、ユーザーが Financial Connections を使用して銀行口座を関連付けた後に、Financial Connections アカウントの所有権データへのアクセスをリクエストします。 以下は、SetupIntent を作成して銀行口座情報を収集するための最小要件の例です。 ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "flow_directions[]=outbound" \ -d "payment_method_types[]=us_bank_account" ``` レスポンスの SetupIntent には `client_secret` が含まれています。これを使用して、銀行口座情報の収集と確認を処理する Stripe.js のページ上のモーダル UI を起動できます。 `client_secret` は、公開可能キーのみで SetupIntent へのアクセスを提供するため、慎重に扱う必要があります。ログに記録したり、URL に埋め込んだり、その連結アカウント以外に公開されることがないようにしてください。 #### ウェブ ## 支払い方法の詳細を収集する (クライアント側) Stripe.js スクリプトを銀行口座の収集ページに含めるには、このスクリプトを HTML ファイルの head に追加します。 ```html Payout ``` 銀行口座の収集ページで以下の JavaScript を使用して、Stripe.js のインスタンスを作成します。 ```javascript // Set your publishable key. Remember to change this to your live publishable key in production! // See your keys here: https://dashboard.stripe.com/apikeys var stripe = Stripe('<>', { apiVersion: "{{DATE_VERSION}}" }); ``` `SetupIntent` の `client_secret` と連結アカウントユーザーの氏名を `stripe.collectBankAccountForSetup` に渡して、Payment Method を収集します。 ```javascript // Assume you have a form to collect payout accounts var form = document.getElementById('payout-form'); form.addEventListener('submit', (event) => { event.preventDefault(); // clientSecret is the SetupIntent's client_secret property stripe.collectBankAccountForSetup({ clientSecret, params: { payment_method_type: 'us_bank_account', payment_method_data: { billing_details: { // name is required name: 'Jenny Rosen', email: 'jenny@example.com' }, }, }, // Optional, helpful for client-side logic expand: ['payment_method'] }).then(({setupIntent, error}) => { if (error) { // Inform your connected account user that there was an error. console.log(error.message); } else { if (setupIntent.status === "requires_confirmation") { // Your connected account user provided bank account details // When you pass `expand: ['payment_method']` to `collectBankAccountForSetup`, // `setupIntent.payment_method` has data about the Payment Method, including // the Financial Connections Account ID, if your connected account user used // Financial Connections to provide their bank account details. const usedFinancialConnections = typeof setupIntent.payment_method.financial_connections_account === 'string'; console.log(setupIntent.payment_method.id); // => 'pm_1Mb4UkJGNKiWrCEmJ1PS72Cd' return stripe.confirmUsBankAccountSetup(clientSecret).then(({setupIntent, error}) => { if (error) { // Inform your connected account user that there was an error, and check your request logs for errors console.log(error.message); } else { if (setupIntent.status === 'succeeded') { // SetupIntent confirmed, Payment Method attached to the Customer // Your logic to create a payout account could go here } else { // Unable to confirm the SetupIntent, re-fetch the SetupIntent for details } } }); } else { // Your connected account user didn't provide bank account details. You // can re-prompt them using `collectBankAccountForSetup` return null; } } }); }); ``` `collectBankAccountForSetup` は `Promise` を返します。連結アカウントが Stripe.js ダイアログを完了すると、`Promise` は、以下のいずれかのキーが設定された `result` オブジェクトで解決されます。 - 連結アカウントがダイアログを終了したときは `setupIntent` - ダイアログを表示したときに修復不能なエラーが発生した場合は `error` `Promise` が `setupIntent` キーで解決され、`result.setupIntent.status` が `"requires_confirmation"` である場合は、`SetupIntent` `client_secret` を指定して `confirmUsBankAccountSetup` を呼び出し、`SetupIntent` を確定します。 `confirmUsBankAccountSetup` は、`collectBankAccountForSetup` と同じタイプの `result` オブジェクトで解決される `Promise` も返します。正常に完了すると、`result.setupIntent.status` は `"succeeded"` になります。そのため、`SetupIntent` の `payment_method` を使用して、サーバーで銀行口座トークンを作成できます。 `stripe.collectBankAccountForSetup` を呼び出すと、Stripe.js は[認証フロー](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow)を読み込みます。このページ上ダイアログでは、連結アカウントに関する情報を確認でき、金融機関を見つけて選択し、アカウントに安全にログインしてアクセスを確認することができます。 Stripe が ACH が有効な口座への入金のみに対応できるため、デフォルトの場合、連結アカウントの認証フローでは、当座預金口座または普通預金口座のみを追加できます。連結アカウントが金融機関を見つけられない場合や口座を認証できない場合は、口座番号と金融番号を手動で入力することもできます。 手動入力の流れは以下のようになります。 ![手動入力にフォールバックできる認証フロー](https://b.stripecdn.com/docs-statics-srv/assets/manual_fallback.c910f590ec792b6133bb88947332604c.png) 連結アカウントが銀行口座の詳細を手動で入力せずに済むようにする場合は、`SetupIntent` の作成時に `payment_method_options[us_bank_account][verification_method]=instant` を渡します。 ### 入金に使用できる外部口座を作成する (サーバー側) SetupIntent を確定した後、関連付けられている Payment Method を使用して銀行口座トークンを作成します。その後、そのトークンを使用して、外部の入金口座を作成します。 まず、銀行口座トークンを作成します。 ```curl curl https://api.stripe.com/v1/tokens \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "bank_account[payment_method]={{PAYMENTMETHOD_ID}}" \ -d "customer={{CUSTOMER_ID}}" ``` 次に、トークンの ID を使用して、外部の入金口座を作成します。 ```curl curl https://api.stripe.com/v1/accounts/{{ACCOUNT_ID}} \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "external_account={{TOKEN_ID}}" ``` デフォルトでは、外部口座を指定すると、その通貨の新しいデフォルトの外部口座として設定され、デフォルト口座が既存であった場合は、それまでの口座が削除されます。 連結アカウントに入金する準備ができています。入金のための外部口座を作成して管理する方法については、[Create external bank account (外部の銀行口座の作成)](https://docs.stripe.com/api/external_account_bank_accounts/create.md) をご覧ください。 ### Financial Connections アカウントに関するデータを取得する (サーバー側) `payment_method` プロパティが拡張された SetupIntent を取得することで、ユーザーが Financial Connections アカウントを関連付けているかどうかを判断できます。 ```curl curl -G https://api.stripe.com/v1/setup_intents/{{SETUP_INTENT_ID}} \ -u "<>:" \ -d "expand[]=payment_method" ``` 以下のような API レスポンスが返されます。 ```javascript { "id": "{{SETUP_INTENT_ID}}", "object": "setup_intent", // ... "payment_method": { "id": "{{PAYMENT_METHOD_ID}}", "object": "payment_method", // ... "type": "us_bank_account", "us_bank_account": { // ... // the value of "financial_connections_account" may be null "financial_connections_account": "{{FINANCIAL_CONNECTIONS_ACCOUNT_ID}}", // ... } }, // ... } ``` SetupIntent の `payment_method` オブジェクトの `us_bank_account` オブジェクトに `financial_connections_account` プロパティが含まれている場合は、ユーザーは Financial Connections アカウントを関連付けています。`financial_connections_account` 値を使用して、SetupIntent の `payment_method_options[us_bank_account][financial_connections][permissions]` パラメーターで指定されたデータにアクセスしたり、データを更新することができます。ユーザーのデータのプライバシーを保護するために、アクセスできるアカウントデータは、このパラメーターで指定したデータに制限されています。 口座データを取得を開始するには、[残高](https://docs.stripe.com/financial-connections/balances.md)、[所有権](https://docs.stripe.com/financial-connections/ownership.md)、[取引](https://docs.stripe.com/financial-connections/transactions.md)の各データのガイドをご覧ください。 ### (任意)Payment Method を使用して支払いを処理する SetupIntent は `"outbound"` 権限のみをリクエストし、まだ[同意書](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md#web-collect-mandate-and-submit)を表示してユーザーから承認を得られていないため、上記の実装によって収集された PaymentMethod を決済処理に使用することはできません。ユーザーが同じアカウントで支払いを行い、入金を受け取れるようにするには、以下の手順に従います。 1. Create Setup Intent API コールから `flow_directions` パラメーターを削除します。 1. ユーザーから[同意書](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md#web-collect-mandate-and-submit)を収集します。 その他の詳細については、[ACH Direct Debit ガイド](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md)を参照してください。 ユーザーが手動入力フォームを使用して銀行口座情報を指定している場合、この実装パターンでは少額入金確認がトリガーされます。 #### iOS ## Financial Connections に追加の依存関係を含める(クライアント側) [Stripe iOS SDK](https://github.com/stripe/stripe-ios) はオープンソースです。[詳細なドキュメントが提供されており](https://stripe.dev/stripe-ios/index.html)、iOS 13 以降をサポートするアプリと互換性があります。 #### Swift Package Manager SDK をインストールするには、以下のステップに従います。 1. Xcode で、**File (ファイル)** > **Add Package Dependencies… (パッケージ依存関係を追加)** を選択し、リポジトリー URL として `https://github.com/stripe/stripe-ios-spm` を入力します。 1. [リリースページ](https://github.com/stripe/stripe-ios/releases)から最新のバージョン番号を選択します。 1. **StripeFinancialConnections** 製品を[アプリのターゲット](https://developer.apple.com/documentation/swift_packages/adding_package_dependencies_to_your_app)に追加します。 #### CocoaPods 1. まだインストールしていない場合は、[CocoaPods](https://guides.cocoapods.org/using/getting-started.html) の最新バージョンをインストールします。 1. 既存の [Podfile](https://guides.cocoapods.org/syntax/podfile.html) がない場合は、以下のコマンドを実行して作成します。 ```bash pod init ``` 1. この行を `Podfile` に追加します。 ```podfile pod 'StripeFinancialConnections' ``` 1. 以下のコマンドを実行します。 ```bash pod install ``` 1. これ以降は、Xcode でプロジェクトを開く際に、`.xcodeproj` ファイルではなく、必ず `.xcworkspace` ファイルを使用するということを忘れないでください。 1. 今後、SDK の最新バージョンに更新するには、以下を実行します。 ```bash pod update StripeFinancialConnections ``` #### Carthage 1. まだインストールしていない場合は、[Carthage](https://github.com/Carthage/Carthage#installing-carthage) の最新バージョンをインストールします。 1. この行を `Cartfile` に追加します。 ```cartfile github "stripe/stripe-ios" ``` 1. [Carthage のインストール手順](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos)に従います。必ず、[こちら](https://github.com/stripe/stripe-ios/tree/master/StripeFinancialConnections/README.md#manual-linking)にリストされている必要なフレームワークのすべてを埋め込んでください。 1. 今後、SDK の最新バージョンに更新するには、以下のコマンドを実行します。 ```bash carthage update stripe-ios --platform ios ``` #### 手動のフレームワーク 1. Stripe の [GitHub リリースページ](https://github.com/stripe/stripe-ios/releases/latest)に移動して、**Stripe.xcframework.zip** をダウンロードして解凍します。 1. **StripeFinancialConnections.xcframework** を、Xcode プロジェクトの **General (一般) ** 設定の **Embedded Binaries (埋め込みバイナリー)** セクションにドラッグします。**Copy items if needed (必要に応じてアイテムをコピーする)** を必ず選択してください。 1. [こちら](https://github.com/stripe/stripe-ios/tree/master/StripeFinancialConnections/README.md#manual-linking)にリストされている必要なフレームワークのすべてに対して、ステップ 2 を繰り返します。 1. 今後、Stripe の SDK の最新バージョンに更新するには、ステップ 1 から 3 を繰り返します。 > SDK の最新リリースおよび過去バージョンの詳細については、GitHub の [Releases (リリース)](https://github.com/stripe/stripe-ios/releases) ページをご覧ください。リポジトリの[リリースをウォッチ](https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository#watching-releases-for-a-repository)して、新しいリリースの公開時に通知を受け取ることも可能です。 ## 戻り URL を設定する (クライアント側) 顧客はお客様のアプリから離れて、(Safari やバンキングアプリなどで) 認証する場合があります。ユーザーが認証後にアプリに自動的に戻れるようにするには、[カスタム URL スキームを構成](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app)し、URL を SDK に転送するようにアプリのデリゲートを設定します。Stripe は[ユニバーサルリンク](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content)には対応していません。 #### SceneDelegate #### Swift ```swift // This method handles opening custom URL schemes (for example, "your-app://stripe-redirect") func scene(_ scene: UIScene, openURLContexts URLContexts: Set) { guard let url = URLContexts.first?.url else { return } let stripeHandled = StripeAPI.handleURLCallback(with: url) if (!stripeHandled) { // This was not a Stripe url – handle the URL normally as you would } } ``` #### AppDelegate #### Swift ```swift // This method handles opening custom URL schemes (for example, "your-app://stripe-redirect") func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] = [:]) -> Bool { let stripeHandled = StripeAPI.handleURLCallback(with: url) if (stripeHandled) { return true } else { // This was not a Stripe url – handle the URL normally as you would } return false } ``` #### SwiftUI #### Swift ```swift @main struct MyApp: App { var body: some Scene { WindowGroup { Text("Hello, world!").onOpenURL { incomingURL in let stripeHandled = StripeAPI.handleURLCallback(with: incomingURL) if (!stripeHandled) { // This was not a Stripe url – handle the URL normally as you would } } } } } ``` ## 支払い方法の詳細を収集する (クライアント側) `STPCollectBankAccountParams` でクラス関数 `collectUSBankAccountParams` を使用して、`collectBankAccountForSetup` の呼び出しに必要なパラメーターを作成します。ACH ダイレクトデビットの `PaymentMethod` を収集するには、連結アカウントユーザーの氏名を指定する必要があります。 `BankAccountCollector` のインスタンスを作成して、`collectBankAccountForSetup` を呼び出し、銀行口座情報を収集して、`PaymentMethod` を作成し、その `PaymentMethod` を `SetupIntent` に関連付けます。 `SetupIntent` の `client_secret`、戻り先 URL、`STPCollectBankAccountParams` パラメーターを `collectBankAccountForSetup` に渡します。 #### Swift ```swift // Build params let collectParams = STPCollectBankAccountParams.collectUSBankAccountParams(with: name, email: email) // Calling this method displays a dialog for collecting bank account information let bankAccountCollector = STPBankAccountCollector() bankAccountCollector.collectBankAccountForSetup(clientSecret: clientSecret, returnURL: "your-app://stripe-redirect", params: collectParams, from: self) { intent, error in guard let intent = intent else { // handle error return } if case .requiresPaymentMethod = intent.status { // Customer canceled the Financial Connections dialog. Present them with other // payment method type options. } else if case .requiresConfirmation = intent.status { // We collected an account - possibly instantly verified, but possibly // manually-entered. let setupIntentParams = STPSetupIntentConfirmParams(clientSecret: clientSecret, paymentMethodType: .USBankAccount) // Confirm the SetupIntent STPPaymentHandler.shared().confirmSetupIntent( setupIntentParams, with: self ) { (status, intent, error) in switch status { case .failed: // Setup failed case .canceled: // Setup was canceled case .succeeded: // Setup succeeded, Payment Method attached to the Customer // Your logic to create a payout account could go here @unknown default: fatalError() } } } } ``` これは[認証フロー](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow)を読み込みます。このダイアログでは、連結アカウントに関する情報を確認でき、金融機関を見つけて選択し、アカウントに安全にログインしてアクセスを確認することができます。 `collectBankAccountForSetupWithClientSecret` は、`SetupIntent` またはエラーで完了します。`SetupIntent` で完了して、ステータスが `requires_confirmation` である場合は、共有の `STPPaymentHandler` インスタンスで `confirmSetupIntent` を呼び出して、`SetupIntent` を確定します。 `confirmSetupIntent` は、`collectBankAccountForSetupWithClientSecret` と同じパラメーターで完了します。正常に完了すると、`SetupIntent` のステータスは `succeeded` になります。そのため、`SetupIntent` の `payment_method` を使用して、サーバーで銀行口座トークンを作成できます。 Stripe が ACH が有効な口座への入金のみに対応できるため、デフォルトの場合、連結アカウントの認証フローでは、当座預金口座または普通預金口座のみを追加できます。連結アカウントが金融機関を見つけられない場合や口座を認証できない場合は、口座番号と金融番号を手動で入力することもできます。 手動入力の流れは以下のようになります。 ![手動入力にフォールバックできる認証フロー](https://b.stripecdn.com/docs-statics-srv/assets/manual_fallback.c910f590ec792b6133bb88947332604c.png) 連結アカウントが銀行口座の詳細を手動で入力せずに済むようにする場合は、`SetupIntent` の作成時に `payment_method_options[us_bank_account][verification_method]=instant` を渡します。 ### 入金に使用できる外部口座を作成する (サーバー側) SetupIntent を確定した後、関連付けられている Payment Method を使用して銀行口座トークンを作成します。その後、そのトークンを使用して、外部の入金口座を作成します。 まず、銀行口座トークンを作成します。 ```curl curl https://api.stripe.com/v1/tokens \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "bank_account[payment_method]={{PAYMENTMETHOD_ID}}" \ -d "customer={{CUSTOMER_ID}}" ``` 次に、トークンの ID を使用して、外部の入金口座を作成します。 ```curl curl https://api.stripe.com/v1/accounts/{{ACCOUNT_ID}} \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "external_account={{TOKEN_ID}}" ``` デフォルトでは、外部口座を指定すると、その通貨の新しいデフォルトの外部口座として設定され、デフォルト口座が既存であった場合は、それまでの口座が削除されます。 連結アカウントに入金する準備ができています。入金のための外部口座を作成して管理する方法については、[Create external bank account (外部の銀行口座の作成)](https://docs.stripe.com/api/external_account_bank_accounts/create.md) をご覧ください。 ### Financial Connections アカウントに関するデータを取得する (サーバー側) `payment_method` プロパティが拡張された SetupIntent を取得することで、ユーザーが Financial Connections アカウントを関連付けているかどうかを判断できます。 ```curl curl -G https://api.stripe.com/v1/setup_intents/{{SETUP_INTENT_ID}} \ -u "<>:" \ -d "expand[]=payment_method" ``` 以下のような API レスポンスが返されます。 ```javascript { "id": "{{SETUP_INTENT_ID}}", "object": "setup_intent", // ... "payment_method": { "id": "{{PAYMENT_METHOD_ID}}", "object": "payment_method", // ... "type": "us_bank_account", "us_bank_account": { // ... // the value of "financial_connections_account" may be null "financial_connections_account": "{{FINANCIAL_CONNECTIONS_ACCOUNT_ID}}", // ... } }, // ... } ``` SetupIntent の `payment_method` オブジェクトの `us_bank_account` オブジェクトに `financial_connections_account` プロパティが含まれている場合は、ユーザーは Financial Connections アカウントを関連付けています。`financial_connections_account` 値を使用して、SetupIntent の `payment_method_options[us_bank_account][financial_connections][permissions]` パラメーターで指定されたデータにアクセスしたり、データを更新することができます。ユーザーのデータのプライバシーを保護するために、アクセスできるアカウントデータは、このパラメーターで指定したデータに制限されています。 口座データを取得を開始するには、[残高](https://docs.stripe.com/financial-connections/balances.md)、[所有権](https://docs.stripe.com/financial-connections/ownership.md)、[取引](https://docs.stripe.com/financial-connections/transactions.md)の各データのガイドをご覧ください。 ### (任意)Payment Method を使用して支払いを処理する SetupIntent は `"outbound"` 権限のみをリクエストし、まだ[同意書](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md#web-collect-mandate-and-submit)を表示してユーザーから承認を得られていないため、上記の実装によって収集された PaymentMethod を決済処理に使用することはできません。ユーザーが同じアカウントで支払いを行い、入金を受け取れるようにするには、以下の手順に従います。 1. Create Setup Intent API コールから `flow_directions` パラメーターを削除します。 1. ユーザーから[同意書](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md#web-collect-mandate-and-submit)を収集します。 その他の詳細については、[ACH Direct Debit ガイド](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md)を参照してください。 ユーザーが手動入力フォームを使用して銀行口座情報を指定している場合、この実装パターンでは少額入金確認がトリガーされます。 #### Android ## Financial Connections に追加の依存関係を含める(クライアント側) [Stripe Android SDK](https://github.com/stripe/stripe-android) はオープンソースであり、[詳細なドキュメントが提供されています](https://stripe.dev/stripe-android/)。 SDK をインストールするには、[app/build.gradle](https://developer.android.com/studio/build/dependencies) ファイルの `dependencies` ブロックに `financial-connections` を追加します。 #### Kotlin ```kotlin plugins { id("com.android.application") } android { ... } dependencies { // ... // Financial Connections Android SDK implementation("com.stripe:financial-connections:23.8.0") } ``` > SDK の最新リリースおよび過去バージョンの詳細については、GitHub の [Releases](https://github.com/stripe/stripe-android/releases) ページをご覧ください。新しいリリースの公開時に通知を受け取るには、[リポジトリのリリースを確認](https://docs.github.com/en/github/managing-subscriptions-and-notifications-on-github/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository)してください。 ## 支払い方法の詳細を収集する (クライアント側) `CollectBankAccountConfiguration.USBankAccount` を使用し、`presentWithSetupIntent` の呼び出しに必要なパラメーターを作成します。ACH ダイレクトデビットの `PaymentMethod` を収集するには、連結アカウントユーザーの氏名を指定する必要があります。 入金アクティビティーの `onCreate` 内で CollectBankAccountLauncher インスタンスを初期化して、結果を処理するメソッドを渡します。次に、`presentWithSetupIntent` を呼び出して銀行口座情報を収集し、`PaymentMethod` を作成して、その `PaymentMethod` を `SetupIntent` に関連付けます。 #### Kotlin ```kotlin import androidx.appcompat.app.AppCompatActivity class PayoutActivity : AppCompatActivity() { private lateinit var setupIntentClientSecret: String private lateinit var collectBankAccountLauncher: CollectBankAccountLauncher private val paymentLauncher: PaymentLauncher = PaymentLauncher.Companion.create( this, "YOUR_PUBLISHABLE_KEY", null, ::onPaymentResult ) override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // Create collector collectBankAccountLauncher = CollectBankAccountLauncher.create( this ) { result: CollectBankAccountResult -> when (result) { is CollectBankAccountResult.Completed -> { val intent = result.response.intent if (intent.status == StripeIntent.Status.RequiresPaymentMethod) { // Customer canceled the Financial Connections dialog. Present them with other // payment method type options. } else if (intent.status == StripeIntent.Status.RequiresConfirmation) { // We collected an account - possibly instantly verified, but possibly // manually-entered. // Confirm the SetupIntent val confirmParams = ConfirmSetupIntentParams.create( clientSecret = setupIntentClientSecret, paymentMethodType = PaymentMethod.Type.USBankAccount ) paymentLauncher.confirm(confirmParams) } } is CollectBankAccountResult.Cancelled -> { // handle cancellation } is CollectBankAccountResult.Failed -> { // handle error print("Error: ${result.error}") } } } } fun collectPayoutAccount() { // ... // Build params val collectParams: CollectBankAccountConfiguration = CollectBankAccountConfiguration.USBankAccount( name, email ) // Calling this method triggers the Financial Connections dialog to be displayed collectBankAccountLauncher.presentWithSetupIntent( publishableKey, setupIntentClientSecret, collectParams ) } private fun onPaymentResult(paymentResult: PaymentResult) { when (paymentResult) { is PaymentResult.Completed -> { // Setup succeeded, Payment Method attached to the Customer // Your logic to create a payout account could go here } is PaymentResult.Canceled -> { // handle cancel flow } is PaymentResult.Failed -> { // handle failures } } } } ``` これは[認証フロー](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow)を読み込みます。このダイアログでは、連結アカウントに関する情報を確認でき、金融機関を見つけて選択し、アカウントに安全にログインしてアクセスを確認することができます。 `CollectBankAccountLauncher` は、`SetupIntent` またはエラーを含む result オブジェクトで完了します。`SetupIntent` で完了して、ステータスが `"requires_confirmation"` である場合は、`PaymentLauncher` インスタンスで `confirm` メソッドを使用して `SetupIntent` を確定します。 完了すると、`confirm` は、[PaymentResult](https://stripe.dev/stripe-android/payments-core/com.stripe.android.payments.paymentlauncher/-payment-result/index.html?query=sealed%20class%20PaymentResult%20:%20Parcelable) オブジェクトを指定して設定可能なメソッドを呼び出します。正常に完了すると、`PaymentResult` オブジェクトは `PaymentResult.Completed` になります。そのため、`SetupIntent` の `payment_method` を使用して、サーバーで銀行口座トークンを作成できます。 Stripe が ACH が有効な口座への入金のみに対応できるため、デフォルトの場合、連結アカウントの認証フローでは、当座預金口座または普通預金口座のみを追加できます。連結アカウントが金融機関を見つけられない場合や口座を認証できない場合は、口座番号と金融番号を手動で入力することもできます。 手動入力の流れは以下のようになります。 ![手動入力にフォールバックできる認証フロー](https://b.stripecdn.com/docs-statics-srv/assets/manual_fallback.c910f590ec792b6133bb88947332604c.png) 連結アカウントが銀行口座の詳細を手動で入力せずに済むようにする場合は、`SetupIntent` の作成時に `payment_method_options[us_bank_account][verification_method]=instant` を渡します。 ### 入金に使用できる外部口座を作成する (サーバー側) SetupIntent を確定した後、関連付けられている Payment Method を使用して銀行口座トークンを作成します。その後、そのトークンを使用して、外部の入金口座を作成します。 まず、銀行口座トークンを作成します。 ```curl curl https://api.stripe.com/v1/tokens \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "bank_account[payment_method]={{PAYMENTMETHOD_ID}}" \ -d "customer={{CUSTOMER_ID}}" ``` 次に、トークンの ID を使用して、外部の入金口座を作成します。 ```curl curl https://api.stripe.com/v1/accounts/{{ACCOUNT_ID}} \ -u "<>:" \ -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \ -d "external_account={{TOKEN_ID}}" ``` デフォルトでは、外部口座を指定すると、その通貨の新しいデフォルトの外部口座として設定され、デフォルト口座が既存であった場合は、それまでの口座が削除されます。 連結アカウントに入金する準備ができています。入金のための外部口座を作成して管理する方法については、[Create external bank account (外部の銀行口座の作成)](https://docs.stripe.com/api/external_account_bank_accounts/create.md) をご覧ください。 ### Financial Connections アカウントに関するデータを取得する (サーバー側) `payment_method` プロパティが拡張された SetupIntent を取得することで、ユーザーが Financial Connections アカウントを関連付けているかどうかを判断できます。 ```curl curl -G https://api.stripe.com/v1/setup_intents/{{SETUP_INTENT_ID}} \ -u "<>:" \ -d "expand[]=payment_method" ``` 以下のような API レスポンスが返されます。 ```javascript { "id": "{{SETUP_INTENT_ID}}", "object": "setup_intent", // ... "payment_method": { "id": "{{PAYMENT_METHOD_ID}}", "object": "payment_method", // ... "type": "us_bank_account", "us_bank_account": { // ... // the value of "financial_connections_account" may be null "financial_connections_account": "{{FINANCIAL_CONNECTIONS_ACCOUNT_ID}}", // ... } }, // ... } ``` SetupIntent の `payment_method` オブジェクトの `us_bank_account` オブジェクトに `financial_connections_account` プロパティが含まれている場合は、ユーザーは Financial Connections アカウントを関連付けています。`financial_connections_account` 値を使用して、SetupIntent の `payment_method_options[us_bank_account][financial_connections][permissions]` パラメーターで指定されたデータにアクセスしたり、データを更新することができます。ユーザーのデータのプライバシーを保護するために、アクセスできるアカウントデータは、このパラメーターで指定したデータに制限されています。 口座データを取得を開始するには、[残高](https://docs.stripe.com/financial-connections/balances.md)、[所有権](https://docs.stripe.com/financial-connections/ownership.md)、[取引](https://docs.stripe.com/financial-connections/transactions.md)の各データのガイドをご覧ください。 ### (任意)Payment Method を使用して支払いを処理する SetupIntent は `"outbound"` 権限のみをリクエストし、まだ[同意書](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md#web-collect-mandate-and-submit)を表示してユーザーから承認を得られていないため、上記の実装によって収集された PaymentMethod を決済処理に使用することはできません。ユーザーが同じアカウントで支払いを行い、入金を受け取れるようにするには、以下の手順に従います。 1. Create Setup Intent API コールから `flow_directions` パラメーターを削除します。 1. ユーザーから[同意書](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md#web-collect-mandate-and-submit)を収集します。 その他の詳細については、[ACH Direct Debit ガイド](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md)を参照してください。 ユーザーが手動入力フォームを使用して銀行口座情報を指定している場合、この実装パターンでは少額入金確認がトリガーされます。 #### React Native ## 支払い方法の詳細を収集する (クライアント側) `SetupIntent` の `client_secret` と連結アカウントユーザーの氏名を `collectBankAccountForSetup` に渡して、Payment Method を収集します。 ```javascript import {collectBankAccountForSetup, confirmSetup} from '@stripe/stripe-react-native'; export default function PayoutAccountCollectionButton() { // Get SetupIntent client secret, connected account user's full name, and email address. // in this example, from a custom hook. const {clientSecret, name, email} = useMyCustomState(); const handleCollectBankAccountPress = async (clientSecret) => { const {setupIntent, error} = await collectBankAccountForSetup( clientSecret, { paymentMethodType: 'USBankAccount', paymentMethodData: { billingDetails: { name, email } } }, ); if (error) { // Inform your connected account user that there was an error. } else if (setupIntent) { if (setupIntent.status === SetupIntents.Status.RequiresConfirmation) { // Your connected account user provided bank account details // Confirm the SetupIntent const {error: confirmError, setupIntent: confirmedSetupIntent} = await confirmSetup(clientSecret, { type: 'USBankAccount' }); if (confirmError) { // Unable to confirm the SetupIntent, inform your connected account user there was an error } else if (confirmedSetupIntent) { if (confirmedSetupIntent.status === SetupIntents.Status.Succeeded) { // Setup succeeded, Payment Method attached to the Customer // Your logic to create a payout account could go here } else { // Unable to confirm the SetupIntent, re-fetch the SetupIntent for details } } } else { // Connected account user didn't link an account or provide details manually } } }; return (