ユーザーの本人確認書類を確認する

セッションを作成して、本人確認書類を収集します。

このガイドでは、Stripe Identity を使用して、身分証明書を安全に収集し、確認する方法について説明します。

はじめに

本番環境利用の申請を行う。
Stripe Identity 申請書にご記入ください。
(オプション) ブランディング設定ページでブランド設定をカスタマイズする。

自社のウェブサイト内で書類のアップロードモーダルを表示します。手順は以下のとおりです。

Web ページに、書類のアップロードモーダルを表示する確認ボタンを追加します。
身分証明書が送信されたら、確認ページを表示します。
本人確認の結果を処理します。

Stripe を設定する
サーバ側

まず、Stripe アカウントを登録します。

次に、アプリケーションから Stripe API へアクセスするためにライブラリをインストールします。

Web サイトにボタンを追加する
クライアント側

確認を開始するためのボタンを Web サイトに作成します。

ボタンを追加する

まずは、ページに確認ボタンを追加します。

verification.html
<html>
  <head>
    <title>Verify your identity</title>
  </head>
  <body>
    <button id="verify-button">Verify</button>
  </body>
</html>

ページに Stripe.js ライブラリを追加する

スクリプトタグを HTML ドキュメントに追加することで、ページに Stripe.js を追加します。

verification.html
<html>
  <head>
    <title>Verify your identity</title>
    <script src="https://js.stripe.com/basil/stripe.js"></script>
  </head>
  <body>
    <button id="verify-button">Verify</button>
  </body>
</html>

注

Stripe.js は常に https://js.stripe.com から直接を読み込んでください。バンドルに含めたり、お客様自身でホストしたりすることはできません。

Stripe.js を初期化する

ページに以下の JavaScript を渡し、公開可能な API キーを使用して Stripe.js を初期化します。

verification.html
<html>
  <head>
    <title>Verify your identity</title>
    <script src="https://js.stripe.com/basil/stripe.js"></script>
  </head>
  <body>
    <button id="verify-button">Verify</button>
    <script type="text/javascript">
      // Set your publishable key: remember to change this to your live publishable key in production
      // See your keys here: https://dashboard.stripe.com/apikeys
      var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);
    </script>
  </body>
</html>

書類のアップロードモーダルを表示する新しいボタンをセットアップします。このボタンをクリックすると、ユーザはパスポート、運転免許証、または国際 ID をキャプチャしてアップロードできます。

このモーダルにより、開発時間とメンテナンス時間を節約できるだけでなく、既存のフローの一環として身分証明書を収集できます。さらに、自社のサイトで顧客の個人情報を処理する量が減り、さまざまなプラットフォームと言語のユーザをサポートすることができ、ブランディングに合わせてスタイルをカスタマイズすることも可能です。

VerificationSession を作成する

VerificationSession は、本人確認をプログラムで示したものです。確認のタイプに関する詳細 (実行するチェックの内容など) が含まれています。確認済みの出力フィールドを拡張して、確認済みのデータの詳細を表示できます。

VerificationSession を作成したら、フロントエンドに client secret を送信して、書類のアップロードモーダルを表示します。

VerificationSession を作成するには、サーバー側のエンドポイントが必要です。サーバー側で VerificationSession を作成することにより、悪意のあるユーザーによる確認オプションの上書き、およびお客様のアカウントでの支払いの処理の偽装を防止できます。セッションのメタデータにユーザー参照を含めるか、データベースにセッション ID を保存することで、このエンドポイントに認証を追加します。

注意

client secret を使用することで、フロントエンドで機密データである本人確認書類を収集できるようになります。使用できるのは 1 回限りで、24 時間後に有効期限が切れます。client secret は、記録したり、URL に埋め込んだり、対象のユーザ以外に公開することがないようにしてください。client secret が含まれるすべてのページで必ず TLS を有効化してください。フロントエンドに client secret のみを送信することで、本人確認の設定や結果の漏洩を回避できます。

Web サーバー (localhost:4242 など) を起動し、curl で VerificationSession を作成する POST リクエストを送信して、エンドポイントをテストします。

Command Line
curl -X POST -is "http://localhost:4242/create-verification-session" -d ""

端末に次のようなレスポンスが表示されます。

Command Line
HTTP/1.1 200 OK
Content-Type: application/json

{ id: "vs_QdfQQ6xfGNJR7ogV6", client_secret: "vs_QdfQQ6xfGNJR7ogV6_secret_live_..."  }

確認ボタンにイベントハンドラを追加する

VerificationSession を作成するためのボタンとエンドポイントが用意されています。ボタンを変更してクリックすると、ドキュメントのアップロードモーダルが表示されます。client secret を使用して verifyIdentity にコールを追加します。

verification.html
<html>
  <head>
    <title>Verify your identity</title>
    <script src="https://js.stripe.com/basil/stripe.js"></script>
  </head>
  <body>
    <button id="verify-button">Verify</button>

    <script type="text/javascript">
      // Set your publishable key: remember to change this to your live publishable key in production
      // See your keys here: https://dashboard.stripe.com/apikeys
      var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

      var verifyButton = document.getElementById('verify-button');

      verifyButton.addEventListener('click', function() {
        // Get the VerificationSession client secret using the server-side
        // endpoint you created in step 3.
        fetch('/create-verification-session', {
          method: 'POST',
        })
        .then(function(response) {
          return response.json();
        })
        .then(function(session) {
          // Show the verification modal.
          return stripe.verifyIdentity(session.client_secret);
        })
        .then(function(result) {
          // If `verifyIdentity` fails, you should display the localized
          // error message to your user using `error.message`.
          if (result.error) {
            alert(result.error.message);
          }
        })
        .catch(function(error) {
          console.error('Error:', error);
        });
      });
    </script>
  </body>
</html>

イベントエラーコード

エラーコード	説明
`consent_declined`	ユーザーが Stripe の本人確認を拒否しました。法律顧問に問い合わせて、手動審査など、生体認証以外の本人確認方法を提供する義務があるかどうかご確認ください。
`device_unsupported`	本人確認にはカメラが必要ですが、ユーザーがカメラのないデバイスを使用しています。
`under_supported_age`	Stripe は未成年のユーザーの本人確認を行いません。
`phone_otp_declined`	ユーザーは提供された電話番号を確認できません。
`email_verification_declined`	ユーザーは提供されたメールアドレスを確認できません。

確認ボタンが書類のアップロードモーダルを表示するかどうかテストします。

確認ボタンをクリックします。すると、Stripe の文書のアップロードモーダルが表示されます。
エラーメッセージが表示されないことを確認します。

構築したシステムが機能しない場合:

ブラウザの開発者ツールでネットワークタブを開きます。
確認ボタンをクリックし、サーバ側エンドポイントに対して XHR リクエストが作成されるかどうか確認します (POST /create-verification-session)。
リクエストが 200 ステータスを返すことを確認します。
ボタンクリックリスナー内で console.log(session) を使用して、正しいデータが返されることを確認します。

確認ページを表示する
クライアント側

ユーザフレンドリーな体験を提供するため、ユーザが身分証明書を送信したら、確認のページを表示します。確認が進行中であることをユーザに知らせるために、自社のサイトでページをホストします。

以下のように、最小限の確認ページを作成します。

submitted.html
<html>
  <head><title>Your document was submitted</title></head>
  <body>
    <h1>Thanks for submitting your identity document.</h1>
    <p>
      We are processing your verification.
    </p>
  </body>
</html>

次に、ボタンハンドラを更新し、このページにリダイレクトします。

verification.html
<html>
  <head>
    <title>Verify your identity</title>
    <script src="https://js.stripe.com/basil/stripe.js"></script>
  </head>
  <body>
    <button id="verify-button">Verify</button>

    <script type="text/javascript">
      // Set your publishable key: remember to change this to your live publishable key in production
      // See your keys here: https://dashboard.stripe.com/apikeys
      var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
)

      var verifyButton = document.getElementById('verify-button');

      verifyButton.addEventListener('click', function() {
        // Get the VerificationSession client secret using the server-side
        // endpoint you created in step 3.
        fetch('/create-verification-session', {
          method: 'POST',
        })
        .then(function(response) {
          return response.json();
        })
        .then(function(session) {
          // Show the verification modal.
          return stripe.verifyIdentity(session.client_secret);
        })
        .then(function(result) {
          // If `verifyIdentity` fails, you should display the error message
          // using `error.message`.
          if (result.error) {
            alert(result.error.message);
          } else {
            window.location.href = 'submitted.html';
          }
        })
        .catch(function(error) {
          console.error('Error:', error);
        });
      });
    </script>
  </body>
</html>

確認ページをテストする

確認ページが機能することをテストする

確認ボタンをクリックします。
事前設定されたテストケースを選択してセッションを送信します。
新しい確認ページが表示されることを確認します。
失敗のケース (同意の拒否やカメラの使用拒否など) のフロー全体をテストし、アプリがこれらのケースに問題なく対応できることを確認します。

次に、Stripe ダッシュボードで確認セッションを見つけます。本人確認セッションは、ダッシュボードの VerificationSessions の一覧に表示されます。セッションをクリックすると、セッションの詳細ページに移動します。サマリーセクションには確認結果が含まれ、これをアプリで使用できます。

確認イベントを処理する

書類確認は通常、ユーザーがお客様のサイトにリダイレクトされるとすぐに完了し、API から結果をすぐに取得できます。まれに、書類確認の準備ができていないために、非同期で続行しなければならないことがあります。この場合、確認結果が準備できると Webhook で通知されます。処理が完了すると、VerificationSession のステータスが変更され、processing から verified になります。

セッションのステータスに変化があると、Stripe は以下のイベントを送信します。

イベント名	説明	次のステップ
identity.verification_session.verified	すべての本人確認チェックの処理が完了し、確認のすべてが成功しました。	アプリケーションで関連するアクションをトリガーします。
identity.verification_session.requires_input	すべての本人確認チェックの処理が完了し、少なくとも 1 つの確認が失敗しました。	アプリケーションで関連するアクションをトリガーするとともに、ユーザーに本人確認の再試行を許可できます。

Webhook ハンドラを使用してこれらのイベントを受信し、確定メールの送信、自社データベース内の確認結果の更新、アカウント登録ステップの完了などのアクションを自動化します。ダッシュボードに確認イベントを表示することもできます。

イベントを受信して、ビジネスアクションを実行する

コード使用

Webhook ハンドラを構築してイベントをリッスンし、非同期型のカスタムの確認フローを作成します。Stripe CLI を使用して、ローカルで Webhook の組み込みのテストとデバッグを行います。

カスタム Webhook を作成する

コードなし

ダッシュボードを使用してすべての本人確認を表示し、収集されたデータを調査して、確認の失敗について把握します。

ダッシュボードでテストの確認を表示する