API によるアカウント登録

Stripe の API を使用して、自社のアカウント登録フローを構築します。

With API onboarding, you use the Accounts API to build an onboarding flow, reporting functionality, and communication channels for your users. Stripe can be completely invisible to the account holder. However, your platform is responsible for all interactions with your accounts and for collecting all the information needed to verify them.

Additional responsibilities

With API onboarding, your custom flow must meet all legal and regulatory requirements in the regions where you do business. You must also commit resources to track changes to those requirements and collect updated information on an ongoing basis, at least once every six months. If you want to implement a customized onboarding flow, Stripe strongly recommends that you use embedded onboarding.

要件を定める

以下の要因は、連結アカウントの登録要件に影響します。

連結アカウントの所在国
連結アカウントに適用される利用規約タイプ
連結アカウントでリクエストされるケイパビリティ
ビジネスタイプ (個人か、会社かなど) および company.structure (公共団体か、非上場の共同経営会社かなど)

対話型フォームを使用して、これらの要因を変更すると要件にどのような影響が出るかを確認できます。

要件フォーム

情報を収集するフォームを作成する
クライアント側

ベストプラクティスとして、必須パラメーターをアカウント登録フローの論理グループまたはフォームに分類します。Stripe のパラメーターと論理グループのマッピングをエンコードすることもできます。パラメーターに推奨される論理グループは、サンプルの要件表の 1 列目に表示されています。

必須パラメーターをアプリケーションにエンコードした後で、これらの要件に対応するパラメーターの UI を生成します。パラメーターごとに、以下を含む UI フォームを設計します。

それぞれ対応する国と言語に合わせたパラメーターのラベル
それぞれ対応する国と言語に合わせたパラメーターの説明
必要に応じてデータ検証ロジックと書類のアップロード機能を備えた、パラメーターの入力フィールド

今後パラメーターが追加される可能性を考慮して、アプリケーションロジックを構築することが重要です。たとえば、Stripe が新しいパラメーター、新しい確認、新しいしきい値を導入し、それらを徐々にアカウント登録フローに組み込む必要がある場合が考えられます。

連結アカウントの要件を決めるいずれかの要因を変更すると、収集フォームの調整も必要になります。国と利用規約の種類は変更できませんが、ケイパビリティやビジネスタイプは変更できます。

国や利用規約の種類などの変更不可のフィールドを変更するには、新しい値で連結アカウントを新規作成します。こうすることで、収集フローに組み込む新しい要件が作成されます。
ケイパビリティやビジネスタイプなどの変更可能なフィールドを変更するには、連結アカウントを更新します。こうすることで、収集フローに組み込む新しい要件が作成されます。

Stripe 利用規約への同意を含める

連結アカウントは、有効化する前に Stripe 利用規約に同意する必要があります。Stripe 利用規約を自社の利用規約に含めることができます。

連結アカウントを作成する
サーバー側

プラットフォームがマイナス残高に対する責任を負い、Stripe がプラットフォームアカウントから手数料を回収し、連結アカウントは Stripe がオンラインで提供するダッシュボードにアクセスできない設定で、connected account (連結アカウント) を作成します。連結アカウントに必要なケイパビリティをリクエストします。事前入力できる場合は、ビジネスのタイプや要件に一致するその他の情報を含めます。

または、type を custom に設定し、必要なケイパビリティを指定して連結アカウントを作成することもできます。

国と利用規約への同意を指定しない場合、次のデフォルト値が割り当てられます。

country は、デフォルトでプラットフォームと同じ国に設定されます。
利用規約への同意 (tos_acceptance.service_agreement) は、デフォルトで full に設定されます。

収集する情報を決定する
サーバー側

プラットフォームは、連結アカウントから必要な情報を事前に収集するか (アップフロント)、段階的に収集するか (インクリメンタル) を決定する必要があります。アップフロントアカウント登録では、アカウントの eventually_due 要件を収集するのに対して、インクリメンタルアカウント登録では currently_due 要件のみを収集します。

	アップフロントアカウント登録	インクリメンタルアカウント登録
長所	情報のリクエストは 1 回 (通常) 入金の受け取りや処理能力の維持上の問題が少ない潜在的な不正利用者または後で必須情報の提供を拒むユーザーが明らかになる	連結アカウントを素早く登録できるアカウント登録率が高くなる
短所	連結アカウントの登録には長くかかる場合があるアカウント登録プロセスの完了前に必要な情報量が原因で、正当な新規の連結アカウントが登録を止める可能性がある	進行中の連結アカウントのビジネスを中断させる可能性が高くなる

アップフロントまたはインクリメンタルのどちらのアカウント登録を使用するかを決定するには、連結アカウントが所在する国で必要な情報を確認して、今後期日を迎える要件を把握してください。Stripe は連結アカウントへの影響を最小限に抑えるように努めていますが、時間の経過につれて要件が変化する可能性があることに留意してください。

For connected accounts where you’re responsible for requirement collection, you can customize the behavior of future requirements using the collection_options parameter. Set collection_options.future_requirements to include to collect the account’s future requirements.

アカウント登録方式を導入するには、作成した連結アカウントの要件ハッシュを調査します。要件ハッシュは、連結アカウントを有効化するために収集する必要があるパラメーターの一覧を提供します。

インクリメンタルアカウント登録方式の場合、要件ハッシュの currently_due フィールドを確認して、リストに表示されたパラメーターのみを収集するアカウント登録フローを構築します。
アップフロントアカウント登録方式の場合、要件ハッシュの eventually_due フィールドを確認して、リストに表示されたすべてのパラメーターを収集するアカウント登録フローを構築します。

{
  ...
  "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": []
  },
  ...
}

連結アカウントを更新する
サーバー側

ユーザーが登録フローの各ステップを進めるごとに、連結アカウントオブジェクトを新しい情報で Update (更新) することにより、Stripe は情報が追加され次第、検証できるようになります。Stripe が利用規約への同意を確認した後で、連結アカウントが変更されると、再確認が実行されます。たとえば、連結アカウントの名前と ID 番号を変更した場合、Stripe は本人確認を再実行します。

連結アカウントを更新する際には、すべての確認エラーまたは HTTP エラーコードに対処する必要があります。

確認エラーを処理する
サーバー側

連結アカウントのデータが送信されると、Stripe はそれを確認します。このプロセスには、必要な確認に応じて数分または数時間かかることがあります。このプロセスの進行中、リクエストしたケイパビリティは保留中のステータスになります。

ステータスを確認する

連結アカウントのケイパビリティのステータスは、以下によって取得できます。

Account オブジェクトの capabilities ハッシュで、関連するケイパビリティを確認します。
Capabilities API から直接ケイパビリティをリクエストし、関連するケイパビリティのステータスを確認します。
Webhook エンドポイントで account.updated イベントをリッスンし、関連するケイパビリティの capabilities ハッシュを確認します。

確認が完了すると、ケイパビリティは active になり、連結アカウントで利用できるようになります。アカウントの確認は継続的に実行され、それ以降に確認が失敗すると、ケイパビリティは active から移行します。account.updated イベントをリッスンして、ケイパビリティの状態の変化を検知します。

構築済みの Connect の実装内容が法令を遵守し、稼働中であることを確認するには、アカウントの charges_enabled と payouts_enabled が両方とも true であることを確認します。API を使用するか、account.updated イベントをリッスンすることができます。その他の関連フィールドについて、詳細はアカウントの requirements (要件) ハッシュを確認してください。アプリケーションおよび関連ポリシーに応じてステータスが変化する可能性があるため、単一の値に基づいて実装を確認することはできません。

charges_enabled は、支払いと送金を含む全体的な支払いパスが正しく機能することを確認し、card_payments と transfers ケイパビリティのどちらがアクティブになっているかを評価します。
payouts_enabled は連結アカウントが外部口座に入金できるかを評価します。リスクポリシーによっては、連結アカウントが入金を有効にせずに取引を開始することを許可できます。連結アカウントに支払うには、最終的には入金を有効にする必要があります。

以下のロジックは、連結アカウントに表示するサマリーのステータスを定義するための開始ポイントとして使用できます。

Ruby
# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'


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 = Stripe::Account.list(limit: 10)

accounts.each do |account|
    puts "#{account.id} has state: #{account_state(account)}"
end

注

API を使用して Stripe のリスク審査に対応することはできません。埋め込みコンポーネント、Stripe のホスティング登録、または修復リンクを使用して、連結アカウントが対応できるように設定できます。ダッシュボードを使用して、連結アカウントの代わりにリスク審査に対応することもできます。

account.updated イベントをリッスンします。current_deadline が着信したときにアカウントに currently_due フィールドが含まれている場合は、対応する機能が無効になり、そのフィールドが past_due に追加されます。

アカウントが情報の修正に使用できる明確な指示が記載されたフォームを作成します。アカウントに通知し、次に Accounts API を使用して、修正された情報を送信します。

すべての確認エラーに対処するカスタムフローの作成を計画している場合:

可能性のあるすべての確認エラーとその対処法に関する詳細を確認します。
確認状態をテストします。