本人確認の結果を処理する
本人確認書類を収集するモーダルを表示するコードを記述しました。次に、ユーザーが書類を送信したときに、確認結果をリッスンし、その対応をアプリケーションでトリガできます。
このガイドでは、以下の方法について説明します。
- 本人確認の処理が終了したら、イベント通知を受け取る。
- 確認チェックの成功と失敗を処理する。
- 本番環境でイベントハンドラを有効にする。
本人確認チェックは非同期で行われるため、確認結果がすぐに出力されるわけではありません。処理が完了すると、VerificationSession ステータスが更新され、確認された情報の使用が可能になります。Stripe はセッションでステータスが変化するたびに、イベントを生成します。このガイドでは、Webhook を実装して、確認結果が使用可能になったときにアプリに通知します。
確認セッションのステータスとライフサイクルについは、セッションの仕組みをご覧ください。
Stripe を設定するサーバー側
アプリケーションから Stripe API にアクセスするには、Stripe の公式ライブラリをインストールします。
Webhook を作成して、VerificationSession イベントを処理するサーバー側
Webhook は、Stripe からのリクエストを受信するサーバー上のエンドポイントであり、アカウントで発生するイベントについてお知らせします。このステップでは、VerificationSession のステータス変化に関するイベントを受信するエンドポイントを構築します。
Stripe が未認証のリクエストを送信できるようにするため、Webhook エンドポイントはパブリックアクセスが可能なものである必要があります。Stripe ライブラリとリクエストヘッダーを使用し、イベントを送信したのが Stripe であることを確認する必要があります。
これで、Stripe からの通知をリッスンする基本的な構造とセキュリティが準備できています。次は、Webhook エンドポイントを更新して確認セッションイベントを処理します。
すべてのセッションイベントに、VerificationSession (確認セッション) オブジェクトが含まれます。これには、実行された本人確認チェックに関する詳細が含まれます。セッションイベントに含まれない確認済みの情報を取得する方法については、本人確認結果へのアクセスをご覧ください。
セッションのステータスに変化があると、Stripe は以下のイベントを送信します。
イベント名 | 説明 | 次のステップ |
---|---|---|
identity.verification_session.verified | すべての本人確認チェックの処理が完了し、確認のすべてが成功しました。 | アプリケーションで対応するアクションをトリガします。 |
identity.verification_session.requires_input | すべての本人確認チェックの処理が完了し、少なくとも 1 つの確認が失敗しました。 | アプリケーションで関連するアクションをトリガーするとともに、ユーザーに本人確認の再試行を許可できます。 |
Webhook コードでは identity.verification_session.verified
イベントと identity.verification_session.requires_input
イベントを処理する必要があります。他のセッションイベントに登録して、アプリで追加の対応をトリガすることもできます。
VerificationSession verified
ステータスの変化を処理する
本人確認チェックが完了し、すべての確認が成功すると、identity.verification_session.verified
イベントが送信されます。
イベントハンドラにコードを追加して、すべての確認チェック成功を処理します。
このイベントを処理する際には、次のことも考慮してください。
VerificationSession requires_input
ステータスの変化を処理する
1 つ以上のチェックが失敗した場合、identity.verification_session.requires_input
イベントが送信されます。確認セッションの last_error ハッシュを調べて、特定の失敗の原因を確認して対処できます。
last_error.code
フィールドを使用すると、確認の失敗をプログラムで処理できます。last_error.reason
フィールドには、失敗の理由を示すメッセージが含まれます。このフィールドはユーザーに提示することができます。
イベントエラーコード
イベントハンドラにコードを追加して、確認チェック失敗を処理します。
ユースケースによっては、本人確認に失敗した場合に、確認の再試行をユーザーに許可することが必要になります。その場合、送信試行回数を制限することをお勧めします。
このイベントを処理する際には、次のことも考慮してください。
- 収集された情報を手動で確認する
- 本人確認が失敗したことをユーザーに知らせるメールを送信する
- ユーザーに代替の本人確認方法を提供する
本番環境に移行する
イベントハンドラエンドポイントを本番環境にデプロイしたら、エンドポイントを設定して、Stripe が本番環境イベントの送信先を認識できるようにします。また、実装を本番環境にスムーズに移行できるようにするため、開発チェックリストを参照することもお勧めします。
Webhook エンドポイントは、ダッシュボードで設定することも、API を使用してプログラムで設定することもできます。
ダッシュボードでエンドポイントを追加する
ダッシュボードの Webhooks 設定ページで、エンドポイントを追加をクリックして、新しい Webhook エンドポイントを追加します。Webhook エンドポイントの URL を入力して、リッスンするイベントを選択します。確認セッションイベントの一覧をご覧ください。
API を使用してエンドポイントを追加する
プログラムで Webhook エンドポイントを作成することもできます。ダッシュボードのフォームと同様に、イベントの宛先とする任意の URL と、登録するイベントタイプを設定できます。
curl https://api.stripe.com/v1/webhook_endpoints \ -u
: \ -d "url"="https://{{DOMAIN}}/my/webhook/endpoint" \ -d "enabled_events[]"="identity.verification_session.verified" \ -d "enabled_events[]"="identity.verification_session.requires_input"sk_test_4eC39HqLyjWDarjtT1zdp7dc