# API によるアカウント登録 Stripe の API を使用して、自社のアカウント登録フローを構築します。 API によるアカウント登録では、Accounts API を使用して、ユーザー向けのアカウント登録フロー、レポート機能、通信チャネルを構築します。アカウント所有者は Stripe を完全に認識できなくなります。ただし、プラットフォームは、アカウントとのすべてのやり取りと、アカウントの確認に必要なすべての情報の収集に対する責任を負うものとします。 > #### その他の責任 > > API によるアカウント登録の場合、構築するカスタムフローは、貴社が事業を行っている地域のすべての法的要件と規制要件を満たすものである必要があります。また、これらの要件の変更を追跡し、少なくとも 6 カ月に一度の頻度で継続的に最新情報を収集するためのリソースを投入する必要があります。カスタマイズしたアカウント登録フローを実装する場合は、[埋め込みアカウント登録](https://docs.stripe.com/connect/embedded-onboarding.md)を利用することを強くお勧めします。 (See full diagram at https://docs.stripe.com/connect/api-onboarding) ## 要件を定める 以下の要因は、連結アカウントの[登録要件](https://docs.stripe.com/connect/required-verification-information.md)に影響します。 - 連結アカウントの所在国 - 連結アカウントに適用される[利用規約タイプ](https://docs.stripe.com/connect/service-agreement-types.md) - 連結アカウントでリクエストされる[ケイパビリティ](https://docs.stripe.com/connect/account-capabilities.md) - [business_type](https://docs.stripe.com/api/accounts/object.md#account_object-business_type) (個人または会社など) および [company.structure](https://docs.stripe.com/api/accounts/object.md#account_object-company-structure) (`public_corporation` または `private_partnership` など) [必須情報確認](https://docs.stripe.com/connect/required-verification-information.md)ツールを使用して、これらの要素の変更が連結アカウントのアカウント登録要件にどのように影響するかを確認します。 ## 情報を収集するフォームを作成する [クライアント側] ベストプラクティスとして、必須パラメーターをアカウント登録フローの論理グループまたはフォームに分類します。Stripe のパラメーターと論理グループのマッピングをエンコードすることもできます。パラメーターに推奨される論理グループは、サンプルの要件表の 1 列目に表示されています。 必須パラメーターをアプリケーションにエンコードした後で、これらの要件に対応するパラメーターの UI を生成します。パラメーターごとに、以下を含む UI フォームを設計します。 - それぞれ対応する国と言語に合わせたパラメーターのラベル - それぞれ対応する国と言語に合わせたパラメーターの説明 - 必要に応じてデータ検証ロジックと書類のアップロード機能を備えた、パラメーターの入力フィールド 今後パラメーターが追加される可能性を考慮して、アプリケーションロジックを構築することが重要です。たとえば、Stripe が新しいパラメーター、新しい確認、新しいしきい値を導入し、それらを徐々にアカウント登録フローに組み込む必要がある場合が考えられます。 連結アカウントの要件を決めるいずれかの要因を変更すると、変更された要件に対応できるように収集フォームも調整する必要があります。[国](https://docs.stripe.com/api/accounts/object.md#account_object-country)と[利用規約の種類](https://docs.stripe.com/api/accounts/object.md#account_object-tos_acceptance-service_agreement)は変更できませんが、[ケイパビリティ](https://docs.stripe.com/api/accounts/object.md#account_object-capabilities)と[事業形態](https://docs.stripe.com/api/accounts/object.md#account_object-business_type)は変更できます。 - 変更不可のフィールドを変更するには、新しい値を使用して新しい連結アカウントを作成し、既存のアカウントを置き換えます。 - 変更可能なフィールドを変更するには、連結アカウントを更新します。 ### Stripe 利用規約への同意を含める 連結アカウントは、本番環境利用を申請する前に Stripe の利用規約に同意する必要があります。[Stripe の利用規約を自社の利用規約に含める](https://docs.stripe.com/connect/updating-service-agreements.md#adding-stripes-service-agreement-to-your-terms-of-service)ことができます。 ## 連結アカウントを作成する [サーバー側] プラットフォームがマイナス残高に対する責任を負い、Stripe がプラットフォームアカウントから手数料を回収し、連結アカウントには Stripe がホストするダッシュボードへのアクセス権を与えないように設定して、[Account (アカウント)](https://docs.stripe.com/api/accounts/create.md) を作成します。連結アカウントに必要なケイパビリティをリクエストします。事業形態と、[要件](https://docs.stripe.com/connect/api-onboarding.md#establish-requirements)に一致するその他の利用可能な情報を事前入力します。 または、`type` を `custom` に設定し、必要なケイパビリティを指定して連結アカウントを作成することもできます。 国と利用規約への同意を指定しない場合、次のデフォルト値が割り当てられます。 - `country` は、デフォルトでプラットフォームと同じ国に設定されます。 - 利用規約への同意 (`tos_acceptance.service_agreement`) は、デフォルトで `full` に設定されます。 > フランスの PSD2 規制に準拠するため、フランスのプラットフォームは [アカウントトークンを使用する義務があります](https://stripe.com/guides/frequently-asked-questions-about-stripe-connect-and-psd2#regulatory-status-of-connect)。トークンのその他のメリットには、連結アカウントから Stripe に直接転送される PII データをプラットフォームに保存する必要がないことが挙げられます。その他の国のプラットフォームの場合、アカウントトークンを使用することをお勧めしますが、これは必須ではありません。 #### コントローラープロパティを使用 ```curl curl https://api.stripe.com/v1/accounts \ -u "<>:" \ -d "controller[losses][payments]=application" \ -d "controller[fees][payer]=application" \ -d "controller[stripe_dashboard][type]=none" \ -d "controller[requirement_collection]=application" \ -d "capabilities[card_payments][requested]=true" \ -d "capabilities[transfers][requested]=true" \ -d business_type=individual \ -d country=US ``` #### アカウントタイプを使用した場合 ```curl curl https://api.stripe.com/v1/accounts \ -u "<>:" \ -d type=custom \ -d "capabilities[card_payments][requested]=true" \ -d "capabilities[transfers][requested]=true" \ -d business_type=individual \ -d country=US ``` ## 収集する情報を決定する [サーバー側] プラットフォームは、連結アカウントから必要な情報を事前に (*アップフロント* (Upfront onboarding is a type of onboarding where you collect all required verification information from your users at sign-up)) 収集するか、段階的に (*インクリメンタル* (Incremental onboarding is a type of onboarding where you gradually collect required verification information from your users. You collect a minimum amount of information at sign-up, and you collect more information as the connected account earns more revenue)) 収集するかを決定する必要があります。アップフロントアカウント登録ではアカウントの `eventually_due` 要件を収集しますが、インクリメンタルアカウント登録では `currently_due` 要件のみを収集します。 | アカウント登録のタイプ | メリット | | ------------ | --------------------------------------------------------------------------------------------------------------- | | **アップフロント** | - 通常、すべての情報に対して 1 回のみのリクエストが必要 - 期限に間に合わなかったために入金や処理に問題が生じる可能性を回避できる - アカウントが情報提供を拒否した場合の潜在的なリスクを、早期に可視化できる | | **インクリメンタル** | - アカウントは多くの情報を提供する必要がないため、素早くアカウント登録できる | アップフロントとインクリメンタルのどちらのアカウント登録を使用するかを決定するには、連結アカウントの所在地とケイパビリティに関する[要件](https://docs.stripe.com/connect/required-verification-information.md)を確認してください。Stripe は連結アカウントへの影響を最小限に抑えるように努めていますが、時間の経過とともに要件が変化する可能性があります。 ### 追加の公開情報を収集 Stripe は各連結アカウントに必要な公開情報を収集します。オンボーディング時に収集する追加フィールドは、ビジネスニーズに応じて選択できます。Stripe が必須としないフィールドはオプションとして表示され、連結アカウントは提供するかどうかを選択できます。 1. ダッシュボードの[公開情報](https://dashboard.stripe.com/settings/connect/onboarding-options/public-details)設定で、**公開情報を収集する**トグルを有効にします。 1. オンボーディング時に連結アカウントに表示するフィールドを選択します。 1. **保存** をクリックします。 #### 利用可能なフィールド 収集できる公開情報は次のとおりです。 | フィールド | 説明 | | ----------------------------------------------------------------- | ----------------------------------------- | | [明細書表記](https://docs.stripe.com/connect/statement-descriptors.md) | 連結アカウントへの決済に対して顧客のカードまたは銀行の明細書に表示されるテキスト。 | | 顧客サポート電話番号 | 連結アカウントに関連するサポートをお客様が依頼できる電話番号。 | | 顧客サポートの住所 | 顧客が連結アカウントへの連絡に使用できる郵送先住所。 | | 顧客サポートメール | 顧客が連結アカウントへの連絡に使用できるメールアドレス。 | > #### 要件はさまざま > > Stripe の要件は、連結アカウントの事業形態、国、リクエストされたケイパビリティによって異なります。必須かどうかにかかわらず、オンボーディング時に常にフィールドが表示されるようにフィールドを有効にしてください。 アカウント登録方式を実装するには、作成した連結アカウントの要件ハッシュを確認します。要件ハッシュは、連結アカウントの本番環境利用を申請するために収集する必要がある情報の一覧を提供します。 - インクリメンタルアカウント登録の場合、要件ハッシュの `currently_due` ハッシュを確認して、それらの要件のみを収集するアカウント登録フローを構築します。 - アップフロントアカウント登録の場合、要件ハッシュの `currently_due` ハッシュと `eventually_due` ハッシュを確認して、それらの要件を収集するアカウント登録フローを構築します。 ```json { ... "requirements": { "alternatives": [], "current_deadline": null, "currently_due": [ "business_profile.product_description", "business_profile.support_phone", "business_profile.url", "external_account", "tos_acceptance.date", "tos_acceptance.ip" ], "disabled_reason": "requirements.past_due", "errors": [],"eventually_due": [ "business_profile.product_description", "business_profile.support_phone", "business_profile.url", "external_account", "tos_acceptance.date", "tos_acceptance.ip" ], "past_due": [], "pending_verification": [] }, ... } ``` ## ライブネス要件を処理する アカウントには、`proof_of_liveness` 要件が設定された 1 つ以上の [Person](https://docs.stripe.com/api/persons.md) オブジェクトを設定できます。`proof_of_liveness` 要件では、シンガポールの [MyInfo](https://www.singpass.gov.sg/main/individuals/) などの電子 ID 情報の収集、または Stripe Identity を使用して書類や顔写真を収集する必要がある場合があります。`proof_of_liveness` 要件のすべてのバリエーションを満たすには、Stripe ホスト型または埋め込み型オンボーディングを使用することをお勧めします。 #### オンライン [Stripe がオンラインで提供するオンボーディング](https://docs.stripe.com/connect/hosted-onboarding.md)で、`proof_of_liveness` 要件のすべてのバリエーションを完了できます。 連結アカウント ID を使用して[アカウントリンクを作成](https://docs.stripe.com/connect/hosted-onboarding.md#create-account-link)し、返された `url` にアカウントを送信します。 ```curl curl https://api.stripe.com/v1/account_links \ -u "<>:" \ -d "account={{CONNECTEDACCOUNT_ID}}" \ --data-urlencode "refresh_url=https://example.com/refresh" \ --data-urlencode "return_url=https://example.com/return" \ -d type=account_onboarding \ -d "collection_options[fields]=currently_due" ``` アカウントは、`proof_of_liveness` 要件と、現在期限が到来しているその他の要件を完了するように求めるプロンプトを受け取ります。Webhook エンドポイントに送信された `account.updated` イベントをリッスンして、アカウントが要件を完了しその情報を更新したときに通知されるようにします。アカウントが要件を完了すると、そのアカウントは指定の `return_url` にリダイレクトされます。 #### 埋込型 [組み込み型オンボーディング](https://docs.stripe.com/connect/embedded-onboarding.md)は、あらゆる形態の `proof_of_liveness` 要件を満たすことができます。 [アカウントセッションの作成](https://docs.stripe.com/api/account_sessions/create.md)時に、`components` パラメーターで `account_onboarding` を指定して、アカウント登録を有効にします。 銀行口座情報を収集する必要がない場合は、`external_account_collection` を無効にします。通常、これはサードパーティーの外部口座収集プロバイダーを利用する Connect プラットフォームに当てはまります。 ```curl curl https://api.stripe.com/v1/account_sessions \ -u "<>:" \ -d "account={{CONNECTEDACCOUNT_ID}}" \ -d "components[account_onboarding][enabled]=true" \ -d "components[account_onboarding][features][external_account_collection]=false" ``` アカウントセッションを作成して [ConnectJS を初期化](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#account-sessions)すると、フロントエンドにアカウント登録コンポーネントを表示できます。 #### JavaScript ```js // Include this element in your HTML const accountOnboarding = stripeConnectInstance.create('account-onboarding'); accountOnboarding.setOnExit(() => { console.log('User exited the onboarding flow'); }); container.appendChild(accountOnboarding); // Optional: make sure to follow our policy instructions above // accountOnboarding.setFullTermsOfServiceUrl('{{URL}}') // accountOnboarding.setRecipientTermsOfServiceUrl('{{URL}}') // accountOnboarding.setPrivacyPolicyUrl('{{URL}}') // accountOnboarding.setCollectionOptions({ // fields: 'eventually_due', // futureRequirements: 'include', // requirements: { // exclude: ['business_profile.product_description'] // } // }) // accountOnboarding.setOnStepChange((stepChange) => { // console.log(`User entered: ${stepChange.step}`); // }); ``` アカウントは、`proof_of_liveness` 要件と、現在期限が到来しているその他の要件を完了するように求めるプロンプトを受け取ります。Webhook エンドポイントに送信された `account.updated` イベントをリッスンして、アカウントが要件を完了しその情報を更新したときに通知されるようにします。アカウントが要件を完了すると、ConnectJS によって `onExit` JavaScript ハンドラが呼び出されます。 #### 本人確認 [Stripe Identity](https://docs.stripe.com/identity.md)を使用して、書類と顔写真を収集することで、`Person` オブジェクトの `proof_of_liveness` 要件を満たすことができます。 [VerificationSession を作成](https://docs.stripe.com/api/identity/verification_sessions/create.md) してください。以下の例に示すように、`related_person` パラメーターを指定して、収集された検証データを `proof_of_liveness` を必要とする `Person` オブジェクトに関連付けます。 ```curl curl https://api.stripe.com/v1/identity/verification_sessions \ -u "<>:" \ -d type=document \ -d "options[document][require_matching_selfie]=true" \ -d "related_person[account]={{CONNECTEDACCOUNT_ID}}" \ -d "related_person[person]={{PERSON_ID}}" ``` `VerificationSession` を作成したら、返された `client_secret` を使用して、[Identity モーダルをユーザーに表示](https://docs.stripe.com/identity/verify-identity-documents.md?platform=web&type=modal#show-modal)するか、ユーザーを `url` にリダイレクトします。確認が完了すると、アカウントが自動的に更新されます。 アカウントが本人確認を完了し、情報を更新すると、Stripe から Webhook エンドポイントに `account.updated` イベントが送信されます。 ## 連結アカウントを更新する [サーバー側] 連結アカウントが登録フローの各ステップを進めるごとに、新しい情報で [Account オブジェクトを更新](https://docs.stripe.com/api/accounts/update.md)します。これにより、Stripe は情報が追加されるとすぐに検証できます。Stripe が利用規約への同意を確認した後で、`Account` が変更されると、再確認が実行されます。たとえば、連結アカウントの名前と ID 番号を変更した場合、Stripe は本人確認を再実行します。 ```curl curl https://api.stripe.com/v1/accounts/{{CONNECTEDACCOUNT_ID}} \ -u "<>:" \ --data-urlencode "business_profile[url]=https://furever.dev" \ -d "tos_acceptance[date]=1609798905" \ -d "tos_acceptance[ip]=8.8.8.8" ``` 連結アカウントを更新する際には、すべての[確認エラー](https://docs.stripe.com/connect/api-onboarding.md#handle-verification-errors)または [HTTP エラーコード](https://docs.stripe.com/error-handling.md)に対処する必要があります。 ## 確認エラーを処理する [サーバー側] 連結アカウントのデータが送信されると、Stripe はそれを確認します。このプロセスには、確認の性質に応じて数分または数時間かかる場合があります。このプロセスの進行中、リクエストしたケイパビリティの `status` は `pending` になります。 ### ステータスを確認する 連結アカウントのケイパビリティのステータスは、以下によって取得できます。 - Account オブジェクトの [capabilities](https://docs.stripe.com/api/accounts/object.md#account_object-capabilities) ハッシュで、関連するケイパビリティを確認します。 - [Capabilities API](https://docs.stripe.com/api/capabilities/retrieve.md) から直接ケイパビリティをリクエストし、関連するケイパビリティのステータスを確認します。 - [Webhook](https://docs.stripe.com/connect/webhooks.md) エンドポイントで `account.updated` [イベント](https://docs.stripe.com/api/events/types.md#event_types-account.updated)をリッスンし、関連するケイパビリティの `capabilities` ハッシュを確認します。 確認が完了すると、ケイパビリティが `active` になり、連結アカウントで利用できるようになります。アカウントの確認は継続的に実行され、それ以降に確認が失敗すると、ケイパビリティは `active` から移行します。`account.updated` イベントをリッスンして、ケイパビリティの状態の変化を検出します。 構築済みの Connect の実装内容が法令を遵守し、稼働中であることを確認するには、アカウントの `charges_enabled` と `payouts_enabled` が両方とも true であることを確認します。API を使用するか、`account.updated` イベントをリッスンすることができます。その他の関連フィールドについて、詳細はアカウントの [requirements (要件)](https://docs.stripe.com/api/accounts/object.md#account_object-requirements) ハッシュを確認してください。アプリケーションおよび関連ポリシーに応じてステータスが変化する可能性があるため、単一の値に基づいて実装を確認することはできません。 - [charges_enabled](https://docs.stripe.com/api/accounts/object.md#account_object-charges_enabled) は、支払いと送金を含む全体的な支払いパスが正しく機能することを確認し、`card_payments` と `transfers` ケイパビリティのどちらがアクティブになっているかを評価します。 - [payouts_enabled](https://docs.stripe.com/api/accounts/object.md#account_object-payouts_enabled) は連結アカウントが外部口座に入金できるかを評価します。リスクポリシーによっては、連結アカウントが入金を有効にせずに取引を開始することを許可できます。連結アカウントに支払うには、[最終的には入金を有効にする必要](https://docs.stripe.com/connect/manage-payout-schedule.md)があります。 以下のロジックは、連結アカウントに表示するサマリーのステータスを定義するための開始ポイントとして使用できます。 #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. client = Stripe::StripeClient.new('<>') def account_state(account) reqs = account.requirements if reqs.disabled_reason && reqs.disabled_reason.include?("rejected") "rejected" elsif account.payouts_enabled && account.charges_enabled if reqs.pending_verification "pending enablement" elsif !reqs.disabled_reason && !reqs.currently_due if !reqs.eventually_due "complete" else "enabled" end else "restricted" end elsif !account.payouts_enabled && account.charges_enabled "restricted (payouts disabled)" elsif !account.charges_enabled && account.payouts_enabled "restricted (charges disabled)" elsif reqs.past_due "restricted (past due)" elsif reqs.pending_verification "pending (disabled)" else "restricted" end end accounts = client.v1.accounts.list({limit: 10}) accounts.each do |account| puts "#{account.id} has state: #{account_state(account)}" end ``` > API を使用して Stripe のリスク審査に対応することはできません。埋め込みコンポーネント、Stripe のホスティング登録、または修復リンクを使用して、連結アカウントが対応できるように設定できます。ダッシュボードを使用して、連結アカウントの代わりにリスク審査に対応することもできます。 [account.updated](https://docs.stripe.com/api/events/types.md#event_types-account.updated) イベントをリッスンします。`current_deadline` が着信したときにアカウントに `currently_due` フィールドが含まれている場合は、対応する機能が無効になり、そのフィールドが `past_due` に追加されます。 アカウントが情報の修正に使用できる明確な指示が記載された[フォームを作成](https://docs.stripe.com/connect/api-onboarding.md#create-forms-to-collect-information)します。アカウントに通知し、次に Accounts API を使用して、[修正された情報を送信](https://docs.stripe.com/connect/api-onboarding.md#update-the-connected-account)します。 (See full diagram at https://docs.stripe.com/connect/api-onboarding) すべての確認エラーに対処するカスタムフローの作成を計画している場合: - 可能性のあるすべての[確認エラーとその対処法](https://docs.stripe.com/connect/handling-api-verification.md)に関する詳細を確認します。 - [確認状態をテストします](https://docs.stripe.com/connect/testing-verification.md)。