コンテンツにスキップ
アカウントを作成
または
サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成
サインイン

注

このページはまだ日本語ではご利用いただけません。より多くの言語で文書が閲覧できるように現在取り組んでいます。準備が整い次第、翻訳版を提供いたしますので、もう少しお待ちください。

Verification Sessions API

Stripe Identity を強力に支える Verification Sessions API の詳細は以下のとおりです。

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

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

VerificationSession の作成

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

  • document - Verify the authenticity and ownership of government-issued identity documents. Can also include a selfie check.
  • id_number: ユーザーの名前、生年月日、国民識別番号を確認します。
Command Line
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 を処理するサーバのエンドポイントを作成する方法をご紹介します。

server.js
// 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.
})();

注

client secret は機密トークンであり、これを使用して検証を完了できます。client secret は、記録したり、URL に埋め込んだり、検証対象のユーザ以外に公開することがないようにしてください。client secret が含まれるすべてのページで TLS を有効化するのを忘れないでください。

検証結果へのアクセス

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

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

{
  "id": "vs_i6zlOIMrvfzmqWx4nrFlAZ9M",
  "object": "identity.verification_session",
  "created": 1610744321,
  "last_error": null,
  "last_verification_report": "vr_olPZDgrCt3A1CdudcRzamyQ8",
  "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
  }
}

If any of the verification checks fail, the session will have a requires_input status. Verification failure details are available in the session last_error hash. The last_error.code value can be used to programmatically handle common verification failures. The last_error.reason will contain a string that explains the failure reason and can be shown to your user.

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

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

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

VerificationSession のキャンセル

You can cancel a VerificationSession at any point before it’s processing or verified. This invalidates the VerificationSession for future submission attempts, and can’t be undone. The session will have a canceled status.

Command Line
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 からでも非表示にできます。

Command Line
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_hBJZ6iIRNPDHWK5WJgLtzdu4",
  "object": "identity.verification_session",
  "created": 1610744321,
  "last_error": null,
  "last_verification_report": "vr_UrPfBk4z9P7yePXYviK3uwdv",
  "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 での検証とシステム内のユーザーとの照合を簡単に行うことができます。

Command Line
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}}

We recommend you don’t store any sensitive information (PII, ID numbers, and so on) in session metadata. Metadata is removed when you redact a VerificationSession.

Session events

Events are created every time a session changes status. Here’s a complete list of the VerificationSession event types:

Event typeDescription
identity.verification_session.createdThe session was created.
identity.verification_session.processingThe user has successfully submitted their information, and verification checks have started processing.
identity.verification_session.verifiedProcessing of all the verification checks have completed, and they’re all successfully verified.
identity.verification_session.requires_inputProcessing of all the verification checks have completed, and at least one of the checks failed.
identity.verification_session.canceledThe session has been canceled and future submission attempts have been disabled. This event is sent when a session is canceled or redacted.
identity.verification_session.redactedThe session was redacted. You must create a webhook endpoint which explicitly subscribes to this event type to access it. Webhook endpoints which subscribe to all events will not include this event type.

You might want to take action in response to certain events, such as emailing your user when a verification fails or succeeds.

Stripe recommends that you listen for events with webhooks.

参照情報

このページはお役に立ちましたか。
はいいいえ
お困りのことがございましたら 、サポートにお問い合わせください。
早期アクセスプログラムにご参加ください。
変更ログをご覧ください。
ご不明な点がございましたら、お問い合わせください。
LLM ですか？llms.txt を読んでください。
Powered by Markdoc