Custom アカウントの登録ソリューション

Stripe は、Custom 連結アカウントのアカウント登録の方法をいくつか提供しています。ビジネスに最適なアカウント登録の方法を選択できます。

Stripe のホスティング登録

Stripe のホスティング登録では、ユーザーを Stripe にリダイレクトして、ブランド定型のインターフェイスでアカウント登録プロセスを完了できます。Account Link を作成して、ユーザーをホスティング登録フローに誘導します。return_url を使用すると、Stripe はユーザーをお客様のアプリケーションに戻せるようになるため、それに応じてお客様は連結アカウントの手順を先に進められるようになります。

Stripe のホスティング登録を実装するには、Stripe のホスティング登録に関するガイドに従ってください。

埋め込みアカウント登録

埋め込みベースのアカウント登録は、Stripe のブランディングが制限された、柔軟にテーマ設定可能なアカウント登録用 UI です。連結アカウントのユーザーは、アプリケーションを離れることなく埋め込みコンポーネントを操作できます。埋め込みベースのアカウント登録では、Accounts API で要件が読み取られた後、Stripe がサポートされているすべての国に適応し、堅牢なデータ検証機能を備えたアカウント登録フォームが生成されます。さらに、埋め込みベースのアカウント登録では、次のすべてが処理されます。

• ビジネスのタイプ
• 会社代表者の設定
• 確認書類のアップロード
• 本人確認とステータス
• 海外の銀行口座
• エラーの状態

埋め込みベースのアカウント登録は数行のコードで実装できますが、API ベースのアカウント登録ではカスタムロジックを構築する必要があります。埋め込みベースのアカウント登録を実装するには、埋め込みコンポーネントガイドに従い、アカウント登録用の埋め込みコンポーネントを実装します。

API ベースのアカウント登録

API ベースのアカウント登録には、対応する Stripe API を呼び出すための、お客様のサイトのアカウント登録ユーザーインターフェイスの各側面の構築が含まれます。実装は Stripe のアカウント登録要件のすべてを満たしている必要があります。

要件を定める

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

• 連結アカウントの所在国
• 連結アカウントに適用される利用規約タイプ
• 連結アカウントでリクエストされるケイパビリティ
• 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 が新しいパラメーター、新しい確認、新しいしきい値を導入し、それらを徐々にアカウント登録フローに組み込む必要がある場合が考えられます。

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

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

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

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

連結アカウントを作成する

Create Account API を使用して、国、利用規約への同意 、希望するケイパビリティ、ビジネスタイプ、要件に合ったその他の情報を指定して連結アカウントを作成します。少なくとも capabilities と type は指定する必要があります。その他のパラメーターを指定しない場合は、以下のデフォルト値が割り当てられます。

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

次のコード例は、個人用の利用規約の全文に基づき、card_payments と transfers ケイパビリティを指定して、Custom の連結アカウントを作成します。

curl https://api.stripe.com/v1/accounts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d country=US \
  -d type=custom \
  -d "capabilities[card_payments][requested]"=true \
  -d "capabilities[transfers][requested]"=true

アカウントにアカウント登録フローをガイドする

連結アカウントを有効にするには次の 2 種類の方法を使用できます。

• インクリメンタルアカウント登録方式: 最小限の必要な情報を事前に収集して、残りの情報を後で収集する
• アップフロントアカウント登録方式: すべての情報を事前に収集する

インクリメンタルアカウント登録方式は、アカウントの初期登録のスピードを上げますが、後から追加の情報収集が必要になります。アップフロントアカウント登録方式は、申請プロセスが長くはなりますが、それと引き換えに連結アカウントのライフサイクル全体で利用の中断を最小限に抑えます。実際のユースケースに合った方式を選択してください。

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

• インクリメンタルアカウント登録方式を選択する場合、要件ハッシュの 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 Account コールを実行し、以前保存した id 値で連結アカウントを識別します。

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"

Stripe は連結アカウントに対するすべての更新を検証します。アカウント登録のステップごとにアカウントを更新することで、ユーザーがアカウント登録フローを継続している間に、Stripe は情報が追加され次第、検証することができます。Stripe が利用規約への同意を確認した後で、連結アカウントに対する変更が発生すると、再確認が実行されます。たとえば、連結アカウントの名前と ID 番号を変更した場合、Stripe は本人確認を再実行します。

連結アカウントを更新する際、Accounts API によって返されるすべての確認エラーや 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

確認エラーを処理する

アカウント登録フローに応じて、確認失敗に対する対処方法を変えます。