API を利用して本人確認を処理する

API を使用して連結アカウントを登録している Connect プラットフォームは、顧客確認 (KYC) のために必要な情報を Stripe に提供して、アカウントのケイパビリティを有効にする必要があります。各プラットフォームは、自ら情報を収集し、Accounts API と Persons API を使用してその情報を Stripe に提供します。その後、Stripe が情報を確認し、必要に応じて詳細を尋ねます。

確認プロセス

連結アカウントの支払いと入金を有効にする前に、Stripe は以下に応じて異なる特定の情報を必要とします。

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

プラットフォームは、ビジネスとユーザに適切なアカウント登録フローを選択して、KYC 要件を満たす必要があります。大まかに言うと、これは必要なすべての情報を事前にまたは段階的に提供することを意味します。いずれにしても、Stripe からのリクエストを監視し、適切に対応するように連携を設定します。

1. Webhook 設定で Connect Webhook URL を設定し、アクティビティ、特に account.updated タイプのイベントを監視します。Persons API を使用する場合は、person.updated イベントも監視する必要があります。
2. アカウントを作成したらすぐに、Account オブジェクトの requirements.currently_due 属性で追加の要件を確認します。追加情報が必要な場合は、ユーザーから入手し、連結アカウントを更新します。
3. account.updated イベント通知を継続的に監視して、requirements ハッシュが変化しているかどうかを確認し、必要に応じて、追加情報をユーザーに求めます。

追加情報を提供する場合、すでに確認済みの詳細を再送信する必要はありません。たとえば、dob がすでに確認されている場合は、それ以降の更新で再度提供する必要はありません。

確認後に情報を変更する

個人または会社が確認された後、制限付きでその情報の一部を変更できます。連結アカウントの設定に基づく制限については、Update Account API をご覧ください。これらの制限以外の変更を行う場合は、サポートにお問い合わせください。

確認が必要かどうかを判断する

Webhook で account.updated イベントを受信するか、API を介してアカウントを取得すると、Account (アカウント) オブジェクトを受信します。Account オブジェクトの charges_enabled 属性と payouts_enabled 属性は、そのアカウントで支払いの作成や入金の受け取りが可能かどうかを示します。

Account オブジェクトには、アカウントの確認に必要な要件を表す requirements ハッシュがあります。

requirements ハッシュには次の配列があります。

• eventually_due: 対応するしきい値に達したかどうかに応じて、収集が必要になる要件。要件が必須になると、その要件は currently_due リストにも表示されます。要件が必須になり、その期日が既存の current_deadline より前の日付である場合、current_deadline は対応するしきい値の発効日に変わります。
• currently_due: Account を active で維持するために current_deadline までに収集する必要がある要件。currently_due は eventually_due のサブセットです。
• past_due: current_deadline より前に確認されなかったために、ケイパビリティが無効化された要件。past_due は currently_due のサブセットです。
• errors: currently_due または past_due の特定の要件を再収集する必要がある、検証および確認の失敗に関する詳細。
  • requirement: エラーに対応する要件を識別します。
  • code: 要件が無効である理由、または確認できない理由を示す列挙値。
  • reason: エラーの詳細を説明する英語のメッセージ。理由文字列でエラーの解決方法を提案することもできます。
• disabled_reason: アカウントが有効化されていない理由、および支払いや送金を処理できない理由を説明します。
• current_deadline: Account を active で維持するために必要な currently_due の要件の収集期日。これは、非表示のケイパビリティを含め、Account がリクエストしたすべてのケイパビリティとリスク要件の最も早い期限を表します。
• pending_verification: 確認または審査の結果に応じて、必須となる可能性がある要件。非同期の確認が保留中でない限り、これは空の配列です。確認に失敗すると、要件は eventually_due、currently_due、または past_due に移行します。失敗した確認と保留中の確認の両方の対象となる要件は、pending_verification のままになることもあります。

以下の例は、アカウントに currently_due の情報、eventually_due の情報、確認の errors を引き起こしている情報が含まれる場合に、requirements ハッシュがどのように表示されるかを示しています。

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  "requirements": {
      "disabled_reason": null,
      "current_deadline": 1529085600,
      "past_due": [],
      "currently_due": [
          "company.tax_id",
          "company.verification.document",
          "tos_acceptance.date",
          "tos_acceptance.ip"
      ],
      "eventually_due": [
          "company.address.city",
          "company.address.line1",
          "company.address.postal_code",
          "company.address.state",
          "company.tax_id",
          "company.verification.document",
          "external_account",
          "tos_acceptance.date",
          "tos_acceptance.ip"
      ],
      "errors": [
          {
            "requirement": "company.verification.document",
            "reason": "The company name on the account couldn't be verified. Either update your business name or upload a document containing the business name.",
            "code": "failed_name_match"
          },
      ]
  },
  ...
}

requirements.currently_due に項目が含まれる場合は、requirements.current_deadline を確認します。current_deadline は、情報が必要となる時点を識別する Unix タイムスタンプです。通常、Stripe が current_deadline までに情報を受信しない場合、そのアカウントでの入金は無効化されます。ただし、状況によっては、このような結果にならない可能性もあります。たとえば、入金がすでに無効になっていて、アカウントが問い合わせに応答しない場合、Stripe が支払いを処理する機能も無効にすることがあります。

これとは別に、requirements.disabled_reason プロパティに値を設定できます。値は、このアカウントで入金や支払いができない理由を説明する文字列です。プラットフォームと連結アカウントは、場合によっては理由を解決したり異議申し立てを行うためのフォームを送信できます。

• Standard アカウントを含む、Stripe ダッシュボードの全機能にアクセスできる連結アカウントは、ダッシュボードにある追加情報 (利用可能な場合) にアクセスできます。
• プラットフォームは、連結アカウントページでアカウントを検索して、アカウントの disabled_reason を特定できます。連結アカウントに代わって追加情報を提供できる場合があります。無効になっている理由が異議申し立てに関連している場合は、対象のアカウント向けに、異議申し立ての解決フォームへのリンクを生成できます。

検証エラーと確認エラー

Account (アカウント) オブジェクトには、requirements.errors 配列が含まれます。この配列は、アカウントとケイパビリティを有効にするために必要とされる検証および確認の要件が満たされていない理由を示します。errors 配列には次の属性が含まれます。

• requirement: currently_due 配列からのどの情報が必要かを指定します。
• code: 発生したエラーのタイプを示します。発生する可能性のあるエラーコードについては、API リファレンスをご覧ください。
• reason: エラーが発生した原因と解決方法について説明します。

要件が currently_due であるアカウントの errors 配列がどのように表示されるかを示す例を以下に示します。この例は、提出された情報を使用してアカウントを有効にできない理由、およびエラーを解決する方法を示しています。検証または確認が失敗した場合、エラー情報とともに、要件が currently_due に再表示される場合があります。これらの更新を受け取るには、Connect Webhook を設定して account.updated イベントを受信します。

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  "requirements": {
      "current_deadline": 1234567800,
      "currently_due": [
          "company.address.line1",
          "{{PERSON_ID}}.verification.document",
      ],
      "errors": [
          {
            "requirement": "company.address.line1",
            "code": "invalid_street_address",
            "reason": "The provided street address cannot be found. Please verify the street name and number are correct in \"10 Downing Street\"",
          },
          {
            "requirement": "{{PERSON_ID}}.verification.document",
            "code": "verification_document_failed_greyscale",
            "reason": "Greyscale documents cannot be read. Please upload a color copy of the document.",
          }
      ]
  },
  ...
}

確認または検証には失敗しても、現在期限が来ている要件がない場合は、Webhook がトリガーされ、必要な情報に最終期日が設定されることが示されます。

事業情報

ビジネスに関する情報が送信されると、Stripe は新しい情報を確認します。たとえば、Stripe は提供されたビジネスの URL が有効で、アクセス可能であり、ビジネスに関する情報が含まれていることを確認する場合があります。ビジネスに関する確認情報のステータスを確認するには、Account の requirements ハッシュを取得します。

以下は、ビジネス情報の確認に関連するエラーのリストです。

明細書表記

Stripe は、アカウントへの設定時に明細書表記と明細書表記のプレフィックスを検証します。たとえば、Stripe は指定された明細書表記がビジネスの説明と一致することを確認する場合があります。明細書表記がビジネスの説明に一致することを検証する際、Stripe はカードネットワークに提供される部分を表す、明細書表記の最初の 22 文字を使用します。ビジネスの説明は、アカウントの business_profile.name、business_profile.url、会社または個人の名前と適合します。

明細書表記に関する本人確認情報のステータスを取得するには、Account オブジェクトの requirements を確認します。以下は、明細書表記の確認に関連するエラーのリストです。

ビジネスの代表者

連結アカウントに関連付けられている人々の情報を収集して提出する必要があります。このプロセスは、連結アカウントが企業か個人かによって異なります。

• 企業のみ:Persons API を使用して、Account に関連付けられた Person に情報を追加します。
• 個人のみ:Account オブジェクトの Persons API または individual ハッシュを使用できます。
• 個人と企業の組み合わせ:Persons API を使用して、アカウントに関連付けられた Person に情報を追加します。これにより、タイプを問わず、すべての連結アカウントに同じプロセスを使用できます。

個人に関する本人確認情報のステータスを取得するには、requirements ハッシュを使用します。

以下は、個人の本人確認に関連するエラーのリストです。

国別の受付可能な確認書類

具体的な書類要件については、国別の受付可能な確認書類をご覧ください。

会社情報

確認プロセスの際に、アカウントの会社に関する情報の収集が必要になる場合があります。

アカウントの会社に関する本人確認情報のステータスを取得するには、Account の company.verification サブハッシュを使用します。

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  ...
  "company": {
    "verification": {
      "document": null
    },
    ...
  },
  ...
}

Account (アカウント) オブジェクトで各本人確認属性の定義を検索できます。

書類確認時の問題に対処する

本人確認書類には、アップロードしたファイル自体の問題や、ファイルを使用して他の情報を確認する際の問題により、多くの要件確認エラーが発生します。発生することが多い問題を認識して対処するために、以下の表に、書類の問題に関連する要件エラーの code 値の一覧と、その解決のためのガイダンスを示します。

以下は、アップロードされた書類ファイルに関連するエラーです。

以下は、本人確認に関連するエラーです。

以下は、ビジネスの確認に関連するエラーです。

以下は、関係の確認に関連するエラーです。

URL 確認のエラーを処理する

EC ビジネスの URL は、カードネットワークの特定の基準に準拠している必要があります。これらの基準に準拠するため、Stripe は URL を審査する際に多くの確認を実施します。EC ビジネスの URL およびその構成要素に関するベストプラクティスについては、ウェブサイトチェックリストをご覧ください。

多くの場合、プラットフォームのダッシュボードから修復リンクを生成することで、ビジネスの URL の確認エラーを解決できます。解決できない場合は、Account の business_profile.url を更新してください。会社のウェブサイトの問題を修正するなど、別の方法でエラーを解決した場合は、Account の URL を他の値に変更し、すぐに元に戻すことで、再確認を開始できます。

API を使用して、URL 関連の問題をすべて解決できるわけではありません。URL 確認エラーの種類によっては、連結アカウントのウェブサイトへのアクセス方法について、またはアカウントが URL 要件への対応を免除されていることの証明方法についての情報が追加で必要です。この種の問題を解決するには、お客様またはお客様の連結アカウントが補足情報を提供しなければなりません。

問題を解決できない場合は、連結アカウントを Stripe サポートの問い合わせ先に誘導してください。

発生することが多い問題を認識して対処するために、次の表に、ビジネスの URL の問題に関連する要件エラーの code 値の一覧と、その解決のためのガイダンスを示します。

ライブネス要件を処理する

アカウントには、proof_of_liveness 要件を持つ 1 人以上の個人を含めることができます。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

本人確認を処理する

場合によっては、Stripe が確認できたアカウントの本人確認情報の量に応じて、さらに 1 種類以上の書類のアップロードをお願いすることがあります。必要な書類は Account の requirements ハッシュに表示されます。

requirements.currently_due の以下の項目は、アップロードする必要がある書類を示しています。

• person.verification.document: 受け入れ可能な形式の身分証明書を撮影したカラー画像が必要です。
• person.verification.additional_document: 公共料金の請求書など、ユーザの住所が確認できる書類を直接撮影したカラー画像が必要です。
• company.verification.document: 会社の定款など、ビジネスの法人 ID 番号を確認できる法人書類の証明書が必要です。

書類は、次の 2 段階のプロセスでアップロードします。

1. Stripe にファイルをアップロードする
2. アカウントにファイルを関連付ける

ファイルをアップロードする

ファイルをアップロードするには、Create File API で POST を使用して、multipart/form-data リクエストの一部としてファイルデータを送信します。

アップロードするファイルは以下の要件を満たしている必要があります。

• カラー画像 (8,000 ピクセル x 8,000 ピクセル以下)
• 10 MB 以下
• 本人確認書類が JPG または PNG 形式である
• 住所または法人確認書類が JPG、PNG、または PDF 形式である

file パラメーターにファイルデータを渡し、書類を保持する Account プロパティまたは Person プロパティに従って purpose パラメーターを設定します。purpose を特定するには、API リファレンスでプロパティを検索します。

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

このリクエストはファイルをアップロードし、トークンを返します。

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

トークンの id 値を使用して、連結アカウントにファイルを関連付けて本人確認を行います。

ファイルを添付する

ファイルをアップロードしてそれに相当するトークンを受け取ったら、Account または Person を更新し、適切なパラメーターにファイル ID を指定します。

以下は、本人確認書類の例です。

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}}
/persons/
{{PERSON_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "verification[document][front]"=
{{FILE_ID}}

以下は、会社書類の例です。

curl https://api.stripe.com/v1/accounts/
{{CONNECTED_ACCOUNT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "company[verification][document][front]"=
{{FILE_ID}}

この更新により、verification.status が pending に変更されます。さらに別の個人を確認する必要がある場合は、Persons API を使用して更新します。

身分証明書を確認する

個人または会社の本人確認要件がすべて満たされると、v2.core.account_person.updated または v2.core.account[identity].updated Webhook 通知がトリガーされ、確認プロセスが完了したことが通知されます。

Stripe による画像の確認には、読み取りやすさに応じて数分から数営業日かかる場合があります。

確認の試行が失敗した場合、関連する要件項目にはエラーが格納され、原因を説明する code と description が含まれます。description には、「提供された画像が読み込めません」などの、判読可能なメッセージが含まれています。このメッセージは、アカウントユーザーに表示しても問題ありませんが、現地の言語に変更されません。code 値は verification_document_not_readable などの文字列であり、これを使用してアカウントユーザー向けのエラーメッセージを現地の言語に変更できます。

確認が失敗すると、v2.core.account_person.updated または v2.core.account[identity].updated Webhook 通知もトリガーされます。

Stripe Identity で提供されるオンラインの書類収集機能

Stripe Identity を使用することで、書類を収集してアカウントに直接関連付ける person.verification.document の要件を満たすことができます。

VerificationSession を作成します。次の例に示すように、related_person パラメーターを指定して、収集された確認データを document を必要とする Person に関連付けます。

curl https://api.stripe.com/v1/identity/verification_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d type=document \
  -d "related_person[account]"=
{{CONNECTED_ACCOUNT_ID}} \
  -d "related_person[person]"=
{{PERSON_ID}}

VerificationSession の作成後、返された client_secret を使用して Identity モーダルをユーザーに表示するか、ユーザーを url にリダイレクトします。確認が完了すると、アカウントが自動的に更新されます。

アカウントが本人確認を完了し、情報を更新すると、Stripe から Webhook エンドポイントに account.updated イベントが送信されます。

リスク確認に対応する

Stripe は、accounts.requirements 属性でリスク要件と規制順守要件を報告します。これらの要件は次のスキーマ <id>.<requirement_description>.<resolution_path>:に従います。

• id は、 Stripe または金融パートナーが必要とする情報を一意に識別します。この ID の前には、リスク確認要件を示す interv_ が常に付与されます。
• requirement_description は、identity_verification や rejection_appeal など、要件を満たすために必要な情報を具体的に説明します。
• resolution_path は、リクエストされた情報をお客様または連結アカウントが提供する方法を指定します。
  • challenge: 連結アカウントは、プロンプトの要求に直接応答する必要があります。多くの場合、銀行口座などの機密情報や、自撮り写真といった口座所有者のみが提供できる情報が必要となります。
  • form: フォームリクエストには連結アカウントが入力するか、またはお客様がアカウントの代理として入力します。
  • support: 要件に直接対応できません。Stripe サポートにお問い合わせください。

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  "requirements": {
      "current_deadline": 1234567800,
      "currently_due": [
          "{{REQUIREMENT_ID}}.restricted_or_prohibited_industry_diligence.form"
      ],
      "pending_verification": [],
      ...
  },
  ...
}

解決パスの要件が満たされると、要件の解決パスの値が support に変わり、その要件が要件ハッシュの pending_verification セクションにも表示されます。Stripe は提出された情報を確認し、解決済みとして要件を終了するか、現在、期限が来ている新しい要件を掲載します。

{
  "id": 
"{{CONNECTED_ACCOUNT_ID}}",
  "object": "account",
  "requirements": {
      "current_deadline": 1234567800,
      "currently_due": [],
      "pending_verification": [
        "{{REQUIREMENT_ID}}.restricted_or_prohibited_industry_diligence.support"
      ],
      ...
  },
  ...
}

リスクと規制順守の要件は、要件のタイプに応じて、以下のいずれかの方法で改善できます。

• Connect の埋め込みコンポーネント: ウェブサイトに直接 Connect コンポーネントを埋め込むことができます。要件が表示されたら、ユーザーをアカウント登録の埋め込みコンポーネントに誘導します。このコンポーネントで、ユーザーは未対応の要件を UI から直接入力するように求められます。または、通知バナーの埋め込みコンポーネントを使用して、未対応の要件についてユーザーに通知します。
• Stripe のホスティング登録: 連結アカウントを誘導するリンクを生成できます。このリンク先では、アカウントリンクからプログラムによって、またはプラットフォームのダッシュボードから手動で未対応の要件に対応することができます。
• アカウントの代理として入力: 自社のプラットフォームのダッシュボードを使用して、連結アカウントの詳細からフォームベースのリスク要件を特定し、そのアカウントの代理として要件に対応することができます。

次の表は、リスクと法令遵守関連の要件の詳細を示しています。