Verification Sessions API
Stripe Identity を強力に支える Verification Sessions API の詳細は以下のとおりです。
Verification Session API を使用して、情報を安全に収集し、本人確認チェックを実行します。この API は、最初の作成から確認プロセス全体まで検証を追跡し、完了時に確認結果を表示します。
Verification Session API を使用してユーザーの書類を確認するための詳細な手順については、関連ガイドのユーザーの本人確認書類を確認するを参照してください。
VerificationSession の作成
VerificationSession を作成する際には、セッションの type を指定して、どの本人確認チェックを実行するかを決定します。
ベストプラクティス
確認プロセスを中断し、後で再開する場合は、新しい VerificationSession を作成するのではなく、同じ VerificationSession の再利用を試してください。各 VerificationSession には固有の ID があり、必要になった際はその ID を使用して取得できます。アプリケーションのデータモデルでは、VerificationSession の ID を保存することで、簡単に取得できます。
VerificationSession を再利用するメリットは、このオブジェクトを使用することで、検証に失敗した場合にそれを追跡しやすくなることです。いずれかのチェックに失敗した場合、VerificationSession のステータスは requires_
になります。
同一人物に対して重複した VerificationSession が誤って作成されるのを防ぐために、VerificationSession を作成する際にはべき等キーを指定することをお勧めします。べき等キーは通常、ユーザー参照など、アプリケーションで本人確認に関連付ける ID に基づいています。
フロントエンドに client secret を渡す
VerificationSession には、個々の VerificationSession に固有のキーである client secret が含まれています。フロントエンドは、この client secret を使用して本人確認を完了します。
client secret を使用するには、サーバ上の VerificationSession から client secret を取得し、フロントエンドに渡す必要があります。クライアントのブラウザの fetch
関数を使用して、ご自身のサーバ上のエンドポイントから client secret を取得できます。一般にこのアプローチは、クライアントが 1 ページのアプリケーションの場合、特に React などの最新のフロントエンドフレームワークで構築されたアプリケーションの場合に最適です。
この例では、client secret を処理するサーバのエンドポイントを作成する方法をご紹介します。
この例では、クライアント側で JavaScript を使用して client secret を取得する方法をご紹介ます。
(async () => { const response = await fetch('/create-verification-session'); const {client_secret: clientSecret} = await response.json(); // Call stripe.verifyIdentity() with the client secret. })();
注
client secret は機密トークンであり、これを使用して検証を完了できます。client secret は、記録したり、URL に埋め込んだり、検証対象のユーザ以外に公開することがないようにしてください。client secret が含まれるすべてのページで TLS を有効化するのを忘れないでください。
検証結果へのアクセス
VerificationSession を送信して処理すると、セッションの status
が更新され、VerificationReport オブジェクトが作成されます。これは通常、数分で完了します。
すべての本人確認チェックに合格すると、ステータスが verified
に変わります。その後、verified_outputs フィールドを拡張して、確認済みのデータを確認できます。
{ "id": "vs_02HUSOCUUzAhG27kTosS33dY", "object": "identity.verification_session", "created": 1610744321, "last_error": null, "last_verification_report": "vr_MDFhlcsrfFMZbP1dwwgKeQKi", "livemode": true, "metadata": {}, "options": { "document": {}, }, "status": "verified", "type": "document", "redaction": null, "url": null, "verified_outputs": { "first_name": "Jenny", "last_name": "Rosen", "address": { "line1": "1234 Main St.", "city": "San Francisco", "state": "CA", "postal_code": "94111", "country": "US" }, "id_number_type": null } }
検証チェックのいずれかが失敗した場合、セッションのステータスは requires_
になります。検証失敗の詳細は、セッションlast_error hash で確認できます。last_error.code 値を使用すると、一般的な検証エラーをプログラムで処理できます。last_error.reason には、失敗の理由を説明する文字列が含まれ、ユーザーに表示できます。
{ "id": "vs_lnFcqzjVAmRCfgemTC2Q4UCZ", "object": "identity.verification_session", "created": 1610744321, "last_error": { "code": "document_expired", "reason": "The document is expired.", }, "last_verification_report": "vr_pzOtmibd8c5uPpTKyNyQivuO", "livemode": true, "metadata": {}, "options": {}, "status": "requires_input", "type": "document", "redaction": null, "url": null, }
ユーザーに確認を再度試行してもらうには、VerificationSession を取得して、新しい URL または client secret を取得する必要があります。
機密データである確認結果へのアクセスについてご紹介します。
VerificationSession のキャンセル
VerificationSession は、processing
または verified
になる前の任意の時点でキャンセルできます。これにより、今後の送信試行で VerificationSession が無効になり、元に戻すことができなくなります。セッションのステータスは canceled
になります。
VerificationSession の伏字処理
確認セッションを非表示にすることを選択する理由の 1 つとして、ユーザーからのデータ削除のリクエストがあります。セッションを非表示にすることで、収集した情報が Stripe API から返されなくなり、ダッシュボードにも表示されなくなります。非表示にされたセッションは、API を使用して取得することはできますが、更新することはできません。セッションは、ダッシュボードからでも API からでも非表示にできます。
非表示にされたセッションでは、個人を特定できる情報 (PII) が入力されていたすべてのフィールドに対してプレースホルダー値が表示されます。このセッションには、非表示プロセスのステータスを示す redaction.status フィールドが含まれています。セッションが非表示にされると、identity.verification_session.redacted Webhook が送信されます。非表示処理には最長で 4 日かかることがありますのでご注意ください。
PII フィールドが拡張された状態で、伏字処理された VerificationSession を取得した場合、これらのフィールドは引き続きレスポンスに表示されますが、その値には PII は含まれません。例として、伏字処理された VerificationSession の verified_
フィールドおよび verified_
フィールドを拡張したレスポンスを次に示します。
{ "id": "vs_qRfv49jAiPzliEmgNMmxBQN3", "object": "identity.verification_session", "created": 1610744321, "last_error": null, "last_verification_report": "vr_mU4lOKzE16K3J9PTTpbdSARW", "livemode": true, "options": {}, "status": "verified", "type": "document", "url": null, "client_secret": null, "redaction": { "status": "redacted" }, "verified_outputs": { "first_name": "[redacted]", "last_name": "[redacted]", "dob": { "year": 1, "month": 1, "day": 1 }, "address": { "line1": "[redacted]", "city": "[redacted]", "state": "[redacted]", "postal_code": "[redacted]", "country": "US" }, "id_number_type": null }, "metadata": {} // Metadata will also be redacted }
VerificationSession に関連付けられている VerificationReport、イベント、およびリクエストログもすべて非表示にされ、ファイルのコンテンツはダウンロードできなくなります。
VerificationSession が processing
状態にある場合は、処理が終了するまで待ってから伏字処理を行ってください。requires_
状態にある VerificationSession を伏字処理すると、自動的にキャンセルされます。
メタデータに情報を保存する
Stripe では、VerificationSession オブジェクトへのメタデータの追加がサポートされています。メタデータは顧客には表示されず、本人確認チェックの成否の要因としても考慮されません。
メタデータを使用して、その他の情報 (お客様にとって意味のある情報) を Stripe アクティビティーに関連付けることができます。追加したメタデータはすべてダッシュボードで確認でき (個々のセッションのページを表示する際など)、一般的なレポートで使用することもできます。一例して、アプリケーションのユーザー ID を、そのユーザーの検証に使用された VerificationSession に関連付けることができます。これにより、Stripe での検証とシステム内のユーザーとの照合を簡単に行うことができます。
機密情報 (PII、ID 番号など) をセッションメタデータに保存しないことをお勧めします。メタデータは、VerificationSession を編集すると削除されます。
セッションイベント
セッションのステータスが変化するたびにイベントが作成されます。VerificationSession イベントタイプの全リストはこちらをご覧ください。
イベントタイプ | 説明 |
---|---|
identity. | セッションが作成されました。 |
identity. | ユーザが情報を送信し、検証チェックは処理を開始しました。 |
identity. | すべての本人確認チェックの処理が完了し、確認のすべてが成功しました。 |
identity. | すべての本人確認チェックの処理が完了し、少なくとも 1 つの確認が失敗しました。 |
identity. | セッションはキャンセルされ、今後の送信試行は無効化されました。このイベントは、セッションがキャンセルされた場合、または非表示にされた場合に送信されます。 |
identity. | セッションが非表示にされました。このイベントタイプにアクセスするには、このイベントタイプに明示的に登録する Webhook エンドポイントを作成する必要があります。すべてのイベントタイプに登録する Webhook エンドポイントには、このイベントタイプは含まれません。 |
検証が失敗または成功したときにユーザにメールを送信するなど、特定のイベントに対してアクションを取ることをお勧めします。
Stripe では、Webhook を使用してイベントをリッスンすることをお勧めします。