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

Connect platforms that onboard connected accounts using the API must provide Stripe with required information for Know Your Customer (KYC) purposes and to enable account capabilities. They must collect the information themselves and use the Accounts and Persons APIs to provide it to Stripe. We then verify the information, asking for more details when needed.

確認プロセス

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

• 連結アカウントの所在国
• 連結アカウントに適用される利用規約タイプ
• 連結アカウントでリクエストされるケイパビリティ
• The business_type (for example, individual or company) and company.structure (for example, public_corporation or 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 ハッシュがあります。

The requirements hash has the following arrays:

• 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 のままになることもあります。

The example below shows what the requirements hash might look like for an account that has some information that’s currently_due, some information that’s eventually_due, and some information that’s raising verification errors.

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

• Connected accounts with access to the full Stripe Dashboard, including Standard accounts, can access additional information (if available) in the Dashboard.
• Platforms can look up an account on the Connected accounts page to determine an account’s disabled_reason. You might be able to provide additional information on behalf of your connected accounts. If the disabled reason is associated with an appeal, you can generate a link to a form for the account to resolve the appeal.

検証エラーと確認エラー

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 がトリガーされ、必要な情報に最終期日が設定されることが示されます。

事業情報

When information about a business is submitted, Stripe verifies the new information. For example, Stripe might verify that the provided business URL is valid, reachable, and includes information about the business. To check the status of verification information regarding a business, retrieve the Account’s requirements hash.

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

明細書表記

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

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

Business representatives

You must collect and submit information about the people associated with a connected account. The process depends on whether your connected accounts are companies or individuals:

• Companies only: Use the Persons API to add the information to a Person associated with the Account.
• Individuals only: You can use the Persons API or the individual hash on the Account object.
• A combination of individuals and companies: Use the Persons API to add the information to a Person associated with the account. That lets you use the same process for all of your connected accounts, regardless of their type.

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

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

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

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

会社情報

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

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

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

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

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

Problems with identity documents, either with uploaded files themselves or with using them to validate other information, cause many requirement verification errors. To help you recognize and handle the most common problems, the tables below list requirement error code values related to document issues and provide guidance for resolving them.

The following errors relate to uploaded document files:

THe following errors relate to identity verification:

The following errors relate to business verification:

The following errors relate to relationship verification:

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

URLs for e-commerce businesses need to conform to certain card network standards. In order to comply with these standards, Stripe conducts a number of verifications when reviewing URLs. To learn about best practices for URLs and common elements for e-commerce businesses, see the website checklist.

In many cases, you can resolve business URL verification errors by generating a remediation link from your platform Dashboard. Otherwise, update the Account’s business_profile.url. If you resolve the error another way, such as by fixing a problem with the company’s website, trigger re-verification by changing the URL on the Account to any other value, then immediately changing it back.

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

If you can’t resolve the issue, direct your connected account to contact Stripe Support.

To help you recognize and handle the most common problems, the following table lists requirement error code values related to issues with the business URL and provides guidance for resolving them.

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

アカウントには、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_Hrs6SAopgFPF0bZXSN3f6ELN
:" \
  -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

本人確認を処理する

In some cases, depending on how much of an account’s identity information Stripe has been able to verify, we might ask you to upload one or more documents. Required documents appear in the Account’s requirements hash.

The following entries in requirements.currently_due identify documents that you must upload:

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

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

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

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

To upload a file, use the Create File API by using a POST to send the file data as part of a multipart/form-data request.

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

• カラー画像 (8,000 ピクセル x 8,000 ピクセル以下)
• 10 MB 以下
• 本人確認書類が JPG または PNG 形式である
• Address or legal entity documents are JPG, PNG, or PDF format

Pass the file data in the file parameter and set the purpose parameter according to the Account or Person property that will hold the document. To identify the purpose, look up the property in the API Reference.

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

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

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

Use the token’s id value to attach the file to a connected account for identity verification.

ファイルを添付する

After you upload the file and receive a representative token, update the Account or Person and provide the file ID in the appropriate parameter.

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

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

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

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

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

身分証明書を確認する

Satisfying all identity verification requirements for a person or company triggers a v2.core.account_person.updated or v2.core.account[identity].updated webhook notification, signaling that the verification process is complete.

Stripe can take anywhere from a few minutes to a few business days to verify an image, depending on its readability.

If the verification attempt fails, the associated requirement entry contains an error with a code and description describing the cause. The description contains a human-readable message such as “The image supplied isn’t readable,” which is safe to present to your account user but isn’t localized. The code value is a string such as verification_document_not_readable, which you can use to localize error messages for your account users.

Verification failure also triggers a v2.core.account_person.updated or v2.core.account[identity].updated webhook notification.

Handle risk verifications

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 のホスティング登録: 連結アカウントを誘導するリンクを生成できます。このリンク先では、アカウントリンクからプログラムによって、またはプラットフォームのダッシュボードから手動で未対応の要件に対応することができます。
• アカウントの代理として入力: 自社のプラットフォームのダッシュボードを使用して、連結アカウントの詳細からフォームベースのリスク要件を特定し、そのアカウントの代理として要件に対応することができます。

The following table provides more detail about possible descriptions of risk- and compliance-related requirements.