Verification Sessions API

Verification Session API を使用して、情報を安全に収集し、本人確認チェックを実行します。この API は、最初の作成から確認プロセス全体まで検証を追跡し、完了時に確認結果を表示します。

Verification Session API を使用してユーザーの書類を確認するための詳細な手順については、関連ガイドのユーザーの本人確認書類を確認するを参照してください。

VerificationSession の作成

VerificationSession を作成する際には、セッションの type を指定して、どの本人確認チェックを実行するかを決定します。

• ドキュメント - 政府発行の身分証明書の信憑性と所有権を確認してください。顔写真チェックを含めることもできます。
• id_number: ユーザーの名前、生年月日、国民識別番号を確認します。

curl https://api.stripe.com/v1/identity/verification_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d type=document

ベストプラクティス

確認プロセスを中断し、後で再開する場合は、新しい 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 を処理するサーバのエンドポイントを作成する方法をご紹介します。

// 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')(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2');

// In the route handler for /create-verification-session:
// Authenticate your user.

// Create the session.
const verificationSession = await stripe.identity.verificationSessions.create({
  type: 'document',
  provided_details: {
    email: 'user@example.com',
  },
  metadata: {
    user_id: '{{USER_ID}}',
  },
});

// Return only the client secret to the frontend.
const clientSecret = verificationSession.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.
})();

検証結果へのアクセス

VerificationSession を送信して処理すると、セッションの status が更新され、VerificationReport オブジェクトが作成されます。これは通常、数分で完了します。

すべての本人確認チェックに合格すると、ステータスが verified に変わります。その後、verified_outputs フィールドを拡張して、確認済みのデータを確認できます。

{
  "id": "vs_OICvDWWJZoUCt9Uc4vz7JzCe",
  "object": "identity.verification_session",
  "created": 1610744321,
  "last_error": null,
  "last_verification_report": "vr_X2eWc25bZshGfDTRkOcQcFHD",
  "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 hash で確認できます。last_error.code 値を使用すると、一般的な検証エラーをプログラムで処理できます。last_error.reason には、失敗の理由を説明する文字列が含まれ、ユーザーに表示できます。

{
  "id": "vs_3T0NInYT2LCu2HQYikz1mbty",
  "object": "identity.verification_session",
  "created": 1610744321,
  "last_error": {
    "code": "document_expired",
    "reason": "The document is expired.",
  },
  "last_verification_report": "vr_czWDTVOIXg4meOh98nLsaBoU",
  "livemode": true,
  "metadata": {},
  "options": {},
  "status": "requires_input",
  "type": "document",
  "redaction": null,
  "url": null,
}

ユーザーに確認を再度試行してもらうには、VerificationSession を取得して、新しい URL または client secret を取得する必要があります。

機密データである確認結果へのアクセスについてご紹介します。

VerificationSession のキャンセル

VerificationSession は、processing または verified になる前の任意の時点でキャンセルできます。これにより、今後の送信試行で VerificationSession が無効になり、元に戻すことができなくなります。セッションのステータスは canceled になります。

curl -X POST https://api.stripe.com/v1/identity/verification_sessions/
{{VERIFICATION_SESSION_ID}}
/cancel \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

VerificationSession の伏字処理

確認セッションを非表示にすることを選択する理由の 1 つとして、ユーザーからのデータ削除のリクエストがあります。セッションを非表示にすることで、収集した情報が Stripe API から返されなくなり、ダッシュボードにも表示されなくなります。非表示にされたセッションは、API を使用して取得することはできますが、更新することはできません。セッションは、ダッシュボードからでも API からでも非表示にできます。

curl -X POST https://api.stripe.com/v1/identity/verification_sessions/
{{VERIFICATION_SESSION_ID}}
/redact \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

非表示にされたセッションでは、個人を特定できる情報 (PII) が入力されていたすべてのフィールドに対してプレースホルダー値が表示されます。このセッションには、非表示プロセスのステータスを示す redaction.status フィールドが含まれています。セッションが非表示にされると、identity.verification_session.redacted Webhook が送信されます。非表示処理には最長で 4 日かかることがありますのでご注意ください。

PII フィールドが拡張された状態で、伏字処理された VerificationSession を取得した場合、これらのフィールドは引き続きレスポンスに表示されますが、その値には PII は含まれません。例として、伏字処理された VerificationSession の verified_outputs フィールドおよび verified_outputs.dob フィールドを拡張したレスポンスを次に示します。

{
  "id": "vs_UXERqWhNE4FkKGUlwKcskFCh",
  "object": "identity.verification_session",
  "created": 1610744321,
  "last_error": null,
  "last_verification_report": "vr_rF4AD0lgEr1L1dXsc4joLQy7",
  "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_action 状態にある VerificationSession を伏字処理すると、自動的にキャンセルされます。

メタデータに情報を保存する

Stripe では、VerificationSession オブジェクトへのメタデータの追加がサポートされています。メタデータは顧客には表示されず、本人確認チェックの成否の要因としても考慮されません。

メタデータを使用して、その他の情報 (お客様にとって意味のある情報) を Stripe アクティビティーに関連付けることができます。追加したメタデータはすべてダッシュボードで確認でき (個々のセッションのページを表示する際など)、一般的なレポートで使用することもできます。一例して、アプリケーションのユーザー ID を、そのユーザーの検証に使用された VerificationSession に関連付けることができます。これにより、Stripe での検証とシステム内のユーザーとの照合を簡単に行うことができます。

curl https://api.stripe.com/v1/identity/verification_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d type=document \
  -d "metadata[user_id]"={{USER_ID}} \
  -d "metadata[reference]"={{IDENTIFIER}}

機密情報 (PII、ID 番号など) をセッションメタデータに保存しないことをお勧めします。メタデータは、VerificationSession を編集すると削除されます。

セッションイベント

セッションのステータスが変化するたびにイベントが作成されます。VerificationSession イベントタイプの全リストはこちらをご覧ください。

検証が失敗または成功したときにユーザにメールを送信するなど、特定のイベントに対してアクションを取ることをお勧めします。

Stripe では、Webhook を使用してイベントをリッスンすることをお勧めします。