ユーザーの本人確認書類を確認する
このガイドでは、Stripe Identity を使用して、身分証明書を安全に収集し、確認する方法について説明します。
はじめに
- 本番環境利用の申請を行う。
- Stripe Identity 申請書にご記入ください。
- (オプション) ブランディング設定ページでブランド設定をカスタマイズする。
自社のウェブサイト内で書類のアップロードモーダルを表示します。手順は以下のとおりです。
- Web ページに、書類のアップロードモーダルを表示する確認ボタンを追加します。
- 身分証明書が送信されたら、確認ページを表示します。
- 本人確認の結果を処理します。
Web サイトにボタンを追加するクライアント側
確認を開始するためのボタンを Web サイトに作成します。
ボタンを追加する
まずは、ページに確認ボタンを追加します。
<html> <head> <title>Verify your identity</title> </head> <body> <button id="verify-button">Verify</button> </body> </html>
ページに Stripe.js ライブラリを追加する
スクリプトタグを HTML ドキュメントに追加することで、ページに Stripe.js を追加します。
<html> <head> <title>Verify your identity</title> <script src="https://js.stripe.com/v3/"></script> </head> <body> <button id="verify-button">Verify</button> </body> </html>
注
Stripe.js は常に https://js.stripe.com
から直接を読み込んでください。バンドルに含めたり、お客様自身でホストしたりすることはできません。
Stripe.js を初期化する
ページに以下の JavaScript を渡し、公開可能な API キーを使用して Stripe.js を初期化します。
<html> <head> <title>Verify your identity</title> <script src="https://js.stripe.com/v3/"></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(
); </script> </body> </html>'pk_test_TYooMQauvdEDq54NiTphI7jx'
書類のアップロードモーダルを表示するクライアント側サーバ側
書類のアップロードモーダルを表示する新しいボタンをセットアップします。このボタンをクリックすると、ユーザはパスポート、運転免許証、または国際 ID をキャプチャしてアップロードできます。
このモーダルにより、開発時間とメンテナンス時間を節約できるだけでなく、既存のフローの一環として身分証明書を収集できます。さらに、自社のサイトで顧客の個人情報を処理する量が減り、さまざまなプラットフォームと言語のユーザをサポートすることができ、ブランディングに合わせてスタイルをカスタマイズすることも可能です。
VerificationSession を作成する
VerificationSession は、本人確認をプログラムで示したものです。確認のタイプに関する詳細 (実行するチェックの内容など) が含まれています。確認済みの出力フィールドを展開して、確認済みのデータの詳細を表示できます。
VerificationSession
を作成したら、フロントエンドに client secret を送信して、書類のアップロードモーダルを表示します。
VerificationSession を作成するには、サーバー側のエンドポイントが必要です。サーバー側で VerificationSession
を作成することにより、悪意のあるユーザーによる確認オプションの上書き、およびお客様のアカウントでの決済処理の偽装を防止できます。セッションのメタデータにユーザー参照を含めるか、データベースにセッション ID を保存することで、このエンドポイントに認証を追加します。
// Set your secret key. Remember to switch to your live secret key in production. // See your keys here: https://dashboard.stripe.com/apikeys const stripe = require('stripe')(
); // In the route handler for /create-verification-session: // Authenticate your user. // Create the session. const verificationSession = await stripe.identity.verificationSessions.create({ type: 'document', metadata: { user_id: '{{USER_ID}}', }, }); // Return only the client secret to the frontend. const clientSecret = verificationSession.client_secret;'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
注意
client secret を使用することで、フロントエンドで機密データである本人確認書類を収集できるようになります。使用できるのは 1 回限りで、24 時間後に有効期限が切れます。client secret は、記録したり、URL に埋め込んだり、対象のユーザ以外に公開することがないようにしてください。client secret が含まれるすべてのページで必ず TLS を有効化してください。フロントエンドに client secret のみを送信することで、本人確認の設定や結果の漏洩を回避できます。
Web サーバー (localhost:4242
など) を起動し、curl で VerificationSession を作成する POST リクエストを送信して、エンドポイントをテストします。
curl -X POST -is "http://localhost:4242/create-verification-session" -d ""
端末に次のようなレスポンスが表示されます。
HTTP/1.1 200 OK Content-Type: application/json { client_secret: "vs_QdfQQ6xfGNJR7ogV6..." }
確認ボタンにイベントハンドラを追加する
VerificationSession を作成するためのボタンとエンドポイントが準備できています。次にボタンを変更して、クリックすると書類のアップロードモーダルが表示されるようにします。client secret を使用して verifyIdentity
にコールを追加します。
<html> <head> <title>Verify your identity</title> <script src="https://js.stripe.com/v3/"></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(
); 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>'pk_test_TYooMQauvdEDq54NiTphI7jx'
イベントエラーコード
エラーコード | 説明 |
---|---|
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)
を使用して、正しいデータが返されることを確認します。
確認ページを表示するクライアント側
ユーザフレンドリーな体験を提供するため、ユーザが身分証明書を送信したら、確認のページを表示します。確認が進行中であることをユーザに知らせるために、自社のサイトでページをホストします。
以下のように、最小限の確認ページを作成します。
<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>
次に、ボタンハンドラを更新し、このページにリダイレクトします。
<html> <head> <title>Verify your identity</title> <script src="https://js.stripe.com/v3/"></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(
) 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>'pk_test_TYooMQauvdEDq54NiTphI7jx'
確認ページをテストする
確認ページが機能することをテストする
- 確認ボタンをクリックします。
- 事前設定されたテストケースを選択してセッションを送信します。
- 新しい確認ページが表示されることを確認します。
- 失敗のケース (同意の拒否やカメラの使用拒否など) のフロー全体をテストし、アプリがこれらのケースに問題なく対応できることを確認します。
次に、Stripe ダッシュボードで確認を探します。確認セッションは、ダッシュボードの VerificationSessions の一覧に表示されます。セッションをクリックすると、セッションの詳細ページに移動します。サマリーセクションには確認の結果が含まれ、これをアプリで使用できます。
確認イベントを処理する
本人確認書類のチェックは非同期であるため、確認結果がすぐに提供されるわけではありません。通常、完了までに 1 ~ 3 分かかります。処理が完了すると、VerificationSession のステータスが変わり、processing
から verified
になります。
セッションのステータスに変化があると、Stripe は以下のイベントを送信します。
イベント名 | 説明 | 次のステップ |
---|---|---|
identity.verification_session.verified | すべての検証チェックの処理が完了し、すべての確認が成功しました。 | アプリケーションで関連するアクションをトリガーします。 |
identity.verification_session.requires_input | すべての検証チェックの処理が完了し、少なくとも 1 つの確認が失敗しました。 | アプリケーションで関連するアクションをトリガーするとともに、ユーザーに本人確認の再試行を許可できます。 |
Webhook ハンドラーを使用してこれらのイベントを受信し、確定メールの送信、お客様のデータベース内の確認結果の更新、アカウント登録ステップの完了などのアクションを自動化します。ダッシュボードに確認イベントを表示することもできます。
イベントを受信して、ビジネスアクションを実行する
コード使用
Webhook ハンドラを構築してイベントをリッスンし、非同期型のカスタムの確認フローを作成します。Stripe CLI を使用して、ローカルで Webhook の組み込みのテストとデバッグを行います。
コードなし
ダッシュボードを使用してすべての本人確認を表示し、収集されたデータを調査して、確認の失敗について把握します。