API によるアカウント登録

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

• 連結アカウントの所在国
• 連結アカウントに適用される利用規約タイプ
• 連結アカウントでリクエストされるケイパビリティ
• business_type (個人または会社など) および company.structure (public_corporation または private_partnership など)

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

// 〒150-0001 東京都渋谷区神宮前1-5-8 神宮前タワービルディング22F
{
  "country": "JP",
  "legal_entity": {
    "address_kana": {
      "country": "JP", // 2-letter country code
      "postal_code": "1500001", // Zip/Postal Code
      "state": "ﾄｳｷﾖｳﾄ", // Prefecture
      "city": "ｼﾌﾞﾔ", // City/Ward
      "town": "ｼﾞﾝｸﾞｳﾏｴ 1-", // Town/cho-me
      "line1": "5-8", // Block/Building number
      "line2": "ｼﾞﾝｸﾞｳﾏｴﾀﾜｰﾋﾞﾙﾃﾞｨﾝｸﾞ22F", // Building details (optional)
    },
    "address_kanji": {
      "country": "JP", // 2-letter country code
      "postal_code": "１５００００１", // Zip/Postal Code
      "state": "東京都", // Prefecture
      "city": "渋谷区", // City/Ward
      "town": "神宮前　１丁目", // Town/cho-me (no kanji numerals)
      "line1": "５－８", // Block/Building number
      "line2": "神宮前タワービルディング22F", // Building details (optional)
    }
  }
}

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d type=custom \
  -d country=JP \
  -d business_type=company \
  -d "capabilities[card_payments][requested]"=true \
  -d "capabilities[transfers][requested]"=true \
  -d "settings[payments][statement_descriptor]"="example descriptor" \
  -d "settings[payments][statement_descriptor_kanji]"="漢字明細" \
  -d "settings[payments][statement_descriptor_kana]"="カナメイサイ"

curl https://files.stripe.com/v1/files \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}" \
  -F "purpose"="account_requirement" \
  -F "file"="@/path/to/a/file"

{
  "id": "file_5dtoJkOhAxrMWb",
  "created": 1403047735,
  "size": 4908
}

curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "documents[proof_of_registration][files][]"=file_5dtoJkOhAxrMWb

curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "company[ownership_declaration][date]"=1609798905 \
  -d "company[ownership_declaration][ip]"="8.8.8.8" \
  --data-urlencode "company[ownership_declaration][user_agent]"="Mozilla/5.0"

curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "company[ownership_declaration][date]"=1609798905 \
  -d "company[ownership_declaration][ip]"="8.8.8.8" \
  --data-urlencode "company[ownership_declaration][user_agent]"="Mozilla/5.0"

curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "company[ownership_declaration][date]"=1609798905 \
  -d "company[ownership_declaration][ip]"="8.8.8.8" \
  --data-urlencode "company[ownership_declaration][user_agent]"="Mozilla/5.0"

curl https://files.stripe.com/v1/files \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}" \
  -F "purpose"="account_requirement" \
  -F "file"="@/path/to/a/file"

{
  "id": "file_5dtoJkOhAxrMWb",
  "created": 1403047735,
  "size": 4908
}

curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "documents[proof_of_registration][files][]"=file_5dtoJkOhAxrMWb

curl https://api.stripe.com/v1/accounts/{{CONNECTED_STRIPE_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "company[ownership_declaration][date]"=1609798905 \
  -d "company[ownership_declaration][ip]"="8.8.8.8" \
  --data-urlencode "company[ownership_declaration][user_agent]"="Mozilla/5.0"

{
  "id": "{{CONNECTED_ACCOUNT_ID}}",
  "requirements": {
    "past_due": [
      "documents.proof_of_ultimate_beneficial_ownership.files",
    ],
    "alternatives": [
      {
        "original_fields_due": [
          "documents.proof_of_ultimate_beneficial_ownership.files",
        ],
        "alternative_fields_due": [
          "company.ownership_exemption_reason",
        ]
      }
    ],
    "errors": [
      {
        "code": "verification_rejected_ownership_exemption_reason",
        "reason": "The ownership exemption reason was rejected.",
        "requirement": "company.ownership_exemption_reason"
      }
    ],
    ...
  },
  ...
}

{
  "id": "{{CONNECTED_ACCOUNT_ID}}",
  "requirements": {
    "past_due": [
      "documents.proof_of_ultimate_beneficial_ownership.files",
    ],
    "errors": [
      {
        "code": "verification_missing_owners",
        "requirement": "documents.proof_of_ultimate_beneficial_ownership.files",
        "reason": "..."
      },
      ...
    ],
    ...
  },
  ...
}

{
  "id": "{{CONNECTED_ACCOUNT_ID}}",
  "requirements": {
    "past_due": [
      "documents.proof_of_ultimate_beneficial_ownership.files",
    ],
    "errors": [
      {
        "code": "verification_document_directors_mismatch",
        "requirement": "documents.proof_of_ultimate_beneficial_ownership.files",
        "reason": "..."
      },
      ...
    ],
    ...
  },
  ...
}

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

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

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

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

連結アカウントの要件を決めるいずれかの要因を変更すると、変更された要件に対応できるように収集フォームも調整する必要があります。国と利用規約の種類は変更できませんが、ケイパビリティと事業形態は変更できます。

• 変更不可のフィールドを変更するには、新しい値を使用して新しい連結アカウントを作成し、既存のアカウントを置き換えます。
• 変更可能なフィールドを変更するには、連結アカウントを更新します。

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

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

プラットフォームがマイナス残高に対する責任を負い、Stripe がプラットフォームアカウントから手数料を回収し、連結アカウントには Stripe がホストするダッシュボードへのアクセス権を与えないように設定して、Account (アカウント) を作成します。連結アカウントに必要なケイパビリティをリクエストします。事業形態と、要件に一致するその他の利用可能な情報を事前入力します。

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

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

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

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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

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

アップフロントとインクリメンタルのどちらのアカウント登録を使用するかを決定するには、連結アカウントの所在地とケイパビリティに関する要件を確認してください。Stripe は連結アカウントへの影響を最小限に抑えるように努めていますが、時間の経過とともに要件が変化する可能性があります。

お客様が必要な情報を収集する責任を負う連結アカウントの場合、collection_options パラメーターを使用して、今後の要件の動作をカスタマイズできます。アカウントの将来の要件を収集するには、collection_options.future_requirements を include に設定します。

アカウント登録方式を実装するには、作成した連結アカウントの要件ハッシュを確認します。要件ハッシュは、連結アカウントの本番環境利用を申請するために収集する必要がある情報の一覧を提供します。

• インクリメンタルアカウント登録の場合、要件ハッシュの currently_due ハッシュを確認して、それらの要件のみを収集するアカウント登録フローを構築します。
• アップフロントアカウント登録の場合、要件ハッシュの 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": []
  },
  ...
}

アカウントには、proof_of_liveness 要件が設定された 1 つ以上の Person (人物) オブジェクトを設定できます。proof_of_liveness 要件では、シンガポールの MyInfo などの電子 ID 認証情報の回収、または Stripe Identity を使用して書類や顔写真を徴収する必要があります。proof_of_liveness 要件のすべてのバリエーションを満たすには、Stripe のホスト型または組み込み型ユーザ登録を使用することをお勧めします。

curl https://api.stripe.com/v1/account_links \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{CONNECTED_ACCOUNT_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

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

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  --data-urlencode "business_profile[url]"="https://furever.dev" \
  -d "tos_acceptance[date]"=1609798905 \
  -d "tos_acceptance[ip]"="8.8.8.8"

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

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

ステータスを確認する

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

• 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 は連結アカウントが外部口座に入金できるかを評価します。リスクポリシーによっては、連結アカウントが入金を有効にせずに取引を開始することを許可できます。連結アカウントに支払うには、最終的には入金を有効にする必要があります。

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

# 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_BQokikJOvBiI2HlWgH4olfQ2'

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

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

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

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

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