Verification Sessions API
Verification Session API を使用して、情報を安全に収集し、検証チェックを実行します。この API は、最初の作成から検証プロセス全体まで検証を追跡し、完了時に検証結果を表示します。
Verification Session API を使用してユーザーの書類を確認するための詳細な手順については、関連ガイドのユーザーの本人確認書類を確認するを参照してください。
VerificationSession の作成
VerificationSession を作成する際には、セッションの type
を指定して、どの検証チェックを実行するかを決定します。
ベストプラクティス
検証プロセスを中断し、後で再開する場合は、新しい VerificationSession を作成するのではなく、同じ VerificationSession の再利用を試してください。各 VerificationSession には固有の ID があり、必要になった際はその ID を使用して取得できます。アプリケーションのデータモデルでは、VerificationSession の ID を保存することで、簡単に取得できます。
VerificationSession を再利用するメリットは、このオブジェクトを使用することで、検証に失敗した場合にそれを追跡しやすくなることです。いずれかのチェックに失敗した場合、VerificationSession のステータスは requires_input
になります。
同一人物に対して重複した 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_u0ekyfFI1X2rPjcbNpB5G3tf", "object": "identity.verification_session", "created": 1610744321, "last_error": null, "last_verification_report": "vr_S4gvOloNyReII1v9R87VZ61x", "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_input
ステータスが表示されます。検証失敗の詳細は、セッションの last_error
ハッシュで確認できます。last_error.code
の値は、一般的な検証の失敗をプログラムで処理するために使用できます。last_error.reason
には、失敗の理由を示す文字列が含まれており、ユーザに提示できます。
{ "id": "vs_Mk79kaRMM0vnr6VEoW0eGDco", "object": "identity.verification_session", "created": 1610744321, "last_error": { "code": "document_expired", "reason": "The document is expired.", }, "last_verification_report": "vr_TDEkZOhADUKspf8mRHwNC0L3", "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_outputs
フィールドおよび verified_outputs.dob
フィールドを拡張したレスポンスを次に示します。
{ "id": "vs_nLDalrM19bx5P1yaAQFnUsAj", "object": "identity.verification_session", "created": 1610744321, "last_error": null, "last_verification_report": "vr_mHzPDHBRr3FaGjoAvxkeppJI", "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 に関連付けられている VerificationReports、イベント、およびリクエストログもすべて伏字処理され、ファイルのコンテンツはダウンロードできなくなります。
VerificationSession が processing
状態にある場合は、処理が終了するまで待ってから伏字処理を行ってください。requires_action
状態にある VerificationSession を伏字処理すると、自動的にキャンセルされます。
メタデータに情報を保存する
Stripe では、VerificationSession オブジェクトへのメタデータの追加がサポートされています。メタデータは顧客には表示されず、検証チェックの成否の要因としても考慮されません。
メタデータを使用して、その他の情報 (お客様にとって意味のある情報) を Stripe アクティビティーに関連付けることができます。追加したメタデータはすべてダッシュボードで確認でき (個々のセッションのページを表示する際など)、一般的なレポートで使用することもできます。一例して、アプリケーションのユーザー ID を、そのユーザーの検証に使用された VerificationSession に関連付けることができます。これにより、Stripe での検証とシステム内のユーザーとの照合を簡単に行うことができます。
セッションのメタデータには、機密情報 (PII、身分証明書番号など) を格納しないことをお勧めします。メタデータは、VerificationSession を伏字処理するときに削除されます。