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: Requirements that you must collect by the current_deadline for the account to remain active. The currently_due requirement is a subset of eventually_due.
• past_due: Requirements that have disabled capabilities because they weren’t verified before the current_deadline. The past_due requirement is a subset of currently_due.
• errors: currently_due または past_due の特定の要件を再収集する必要がある、検証および確認の失敗に関する詳細。
  • requirement: エラーに対応する要件を識別します。
  • code: 要件が無効である理由、または確認できない理由を示す列挙値。
  • reason: エラーの詳細を説明する英語のメッセージ。理由文字列でエラーの解決方法を提案することもできます。
• disabled_reason: Describes why the account isn’t enabled and why it can’t process charges or transfers.
• current_deadline: Date that the requirements in currently_due must be collected by to keep the account active. It represents the earliest deadline across all of the account’s requested capabilities and risk requirements, including any hidden capabilities.
• 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 を特定できます。連結アカウントに代わって追加情報を提供できる場合があります。無効になっている理由が異議申し立てに関連している場合は、対象のアカウント向けに、異議申し立ての解決フォームへのリンクを生成できます。

検証エラーと確認エラー

The Account object includes a requirements.errors array that explains why the validation or verification requirements haven’t been met, which you need to enable your account and capabilities. The errors array has the following attributes:

• 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 object’s requirements hash.

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

明細書表記

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

To retrieve the status of verification information regarding statement descriptors, review the requirements on the Account object. Below is a list of errors related to statement descriptor verification:

ビジネスの代表者

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

• Companies only: Use the Persons API to add the information to a Person object associated with the Account object.
• 個人のみ:Account オブジェクトの Persons API または individual ハッシュを使用できます。
• A combination of individuals and companies: Use the Persons API to add the information to a Person object associated with the account. That lets you use the same process for all of your connected accounts, regardless of their type.

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

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

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

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

会社情報

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

To retrieve the status of verification information regarding an account’s company, use the Account object’s company.verification subhash:

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

You can look up the definition for each verification attribute on the Account object.

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

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

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

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

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

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

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

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

In many cases, you can resolve business URL verification errors by generating a remediation link from your platform Dashboard. Otherwise, update the Account object’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 object to any other value, then immediately changing it back.

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

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

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

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

An account can have one or more Person objects with a proof_of_liveness requirement. A proof_of_liveness requirement might require collection of an electronic ID credential such as MyInfo in Singapore, or by using Stripe Identity to collect a document or selfie. We recommend using Stripe-hosted or embedded onboarding to satisfy all variations of the proof_of_liveness requirement.

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

本人確認を処理する

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 object’s requirements hash.

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 形式である

Pass the file data in the file parameter and set the purpose parameter according to the Account or Person object 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_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 値を使用して、連結アカウントにファイルを関連付けて本人確認を行います。

ファイルを添付する

After you upload the file and receive a representative token, update the Account or Person object 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_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 の要件を満たすことができます。

Create a VerificationSession. Specify the related_person parameter to associate the collected verification data with the Person object requiring the document, as shown in the following example.

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

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