# Verification Sessions API

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

[Verification Session API](https://docs.stripe.com/api/identity/verification_sessions.md) を使用して、情報を安全に収集し、[本人確認チェック](https://docs.stripe.com/identity/verification-checks.md)を実行します。この API は、最初の作成から確認プロセス全体まで検証を追跡し、完了時に確認結果を表示します。

Verification Session API を使用してユーザーの書類を確認するための詳細な手順については、関連ガイドの[ユーザーの本人確認書類を確認する](https://docs.stripe.com/identity/verify-identity-documents.md)を参照してください。

## VerificationSession の作成

[VerificationSession を作成](https://docs.stripe.com/api/identity/verification_sessions/create.md)する際には、セッションの [type](https://docs.stripe.com/api/identity/verification_sessions/create.md#create_identity_verification_session-type) を指定して、どの[本人確認チェック](https://docs.stripe.com/identity/verification-checks.md)を実行するかを決定します。

- [ドキュメント](https://docs.stripe.com/identity/verification-checks.md?type=document) - 政府発行の身分証明書の信憑性と所有権を確認してください。顔写真チェックを含めることもできます。
- [id_number](https://docs.stripe.com/identity/verification-checks.md?type=id-number): ユーザーの名前、生年月日、国民識別番号を確認します。

```curl
curl https://api.stripe.com/v1/identity/verification_sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d type=document
```

### ベストプラクティス

確認プロセスを中断し、後で再開する場合は、新しい VerificationSession を作成するのではなく、同じ VerificationSession の再利用を試してください。各 VerificationSession には固有の ID があり、必要になった際はその ID を使用して[取得](https://docs.stripe.com/api/identity/verification_sessions/retrieve.md)できます。アプリケーションのデータモデルでは、VerificationSession の ID を保存することで、簡単に取得できます。

VerificationSession を再利用するメリットは、このオブジェクトを使用することで、検証に失敗した場合にそれを追跡しやすくなることです。いずれかのチェックに失敗した場合、VerificationSession のステータスは `requires_input` になります。

同一人物に対して重複した VerificationSession が誤って作成されるのを防ぐために、VerificationSession を作成する際には[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)を指定することをお勧めします。べき等キーは通常、ユーザー参照など、アプリケーションで本人確認に関連付ける ID に基づいています。

## フロントエンドに client secret を渡す

VerificationSession には、個々の VerificationSession に固有のキーである [client secret](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-client_secret) が含まれています。フロントエンドは、この client secret を使用して本人確認を完了します。

client secret を使用するには、サーバ上の VerificationSession から client secret を取得し、フロントエンドに渡す必要があります。クライアントのブラウザの `fetch` 関数を使用して、ご自身のサーバ上のエンドポイントから client secret を取得できます。一般にこのアプローチは、クライアントが 1 ページのアプリケーションの場合、特に React などの最新のフロントエンドフレームワークで構築されたアプリケーションの場合に最適です。

この例では、client secret を処理するサーバのエンドポイントを作成する方法をご紹介します。

#### Node.js

```javascript

// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
// Find your keys at https://dashboard.stripe.com/apikeys.
const stripe = require('stripe')('<<YOUR_SECRET_KEY>>');

// 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 を取得する方法をご紹介ます。

```javascript
(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* (TLS refers to the process of securely transmitting data between the client—the app or browser that your customer is using—and your server. This was originally performed using the SSL (Secure Sockets Layer) protocol) を有効化するのを忘れないでください。

## 検証結果へのアクセス

VerificationSession を送信して処理すると、セッションの `status` が更新され、[VerificationReport](https://docs.stripe.com/api/identity/verification_reports/object.md) オブジェクトが作成されます。これは通常、数分で完了します。

すべての本人確認チェックに合格すると、ステータスが `verified` に変わります。その後、[verified_outputs](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-verified_outputs) フィールドを[拡張](https://docs.stripe.com/api/expanding_objects.md)して、確認済みのデータを確認できます。

```json
{
  "id": "vs_orWziM4j7CiRL8J4vQmXgW2w",
  "object": "identity.verification_session",
  "created": 1610744321,
  "last_error": null,
  "last_verification_report": "vr_orWziM4j7CiRL8J4vQmXgW2w",
  "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](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-last_error) hash で確認できます。[last_error.code](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-last_error-code) 値を使用すると、一般的な検証エラーをプログラムで処理できます。[last_error.reason](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-last_error-code) には、失敗の理由を説明する文字列が含まれ、ユーザーに表示できます。

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

ユーザーに確認を再度試行してもらうには、[VerificationSession を取得](https://docs.stripe.com/api/identity/verification_sessions/retrieve.md)して、新しい URL または client secret を取得する必要があります。

[機密データである確認結果へのアクセス](https://docs.stripe.com/identity/access-verification-results.md)についてご紹介します。

## VerificationSession のキャンセル

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

```curl
curl -X POST https://api.stripe.com/v1/identity/verification_sessions/{{IDENTITYVERIFICATIONSESSION_ID}}/cancel \
  -u "<<YOUR_SECRET_KEY>>:"
```

## VerificationSession の伏字処理

確認セッションを非表示にすることを選択する理由の 1 つとして、ユーザーからのデータ削除リクエストがあります。セッションを非表示にすることで、Stripe が個人情報を削除できるようになります。Stripe が収集した個人情報が Stripe API から返されなくなり、ダッシュボードにも表示されなくなります。API を使用して非表示にされた Sessions を[取得](https://docs.stripe.com/api/identity/verification_sessions/retrieve.md)することもできますが、更新することはできません。ダッシュボードまたは API を使用して Sessions を非表示にできます。

```curl
curl -X POST https://api.stripe.com/v1/identity/verification_sessions/{{IDENTITYVERIFICATIONSESSION_ID}}/redact \
  -u "<<YOUR_SECRET_KEY>>:"
```

非表示にされたセッションには、個人を特定できる情報 (PII) が以前に含まれていたすべてのフィールドにプレースホルダー値があります。セッションには、非表示プロセスのステータスを示す [redaction.status](https://docs.stripe.com/api/identity/verification_sessions/object.md#identity_verification_session_object-redaction-status) フィールドが含まれます。セッションが非表示にされると、[identity.verification_session.redacted](https://docs.stripe.com/api/events/types.md#event_types-identity.verification_session.redacted) Webhook が送信されます。非表示には最大で 4 日かかる場合があります。

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

```json

{
  "id": "vs_orWziM4j7CiRL8J4vQmXgW2w",
  "object": "identity.verification_session",
  "created": 1610744321,
  "last_error": null,
  "last_verification_report": "vr_orWziM4j7CiRL8J4vQmXgW2w",
  "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](https://docs.stripe.com/api/identity/verification_reports.md)、[イベント](https://docs.stripe.com/api/events.md)、[リクエストログ](https://dashboard.stripe.com/logs)を非表示にします。[ファイル](https://docs.stripe.com/api/files.md)のコンテンツを削除すると、ダウンロードできなくなります。

VerificationSession が `processing` 状態にある場合は、処理が終了するまで待ってから伏字処理を行ってください。`requires_action` 状態にある VerificationSession を伏字処理すると、自動的にキャンセルされます。

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

Stripe では、VerificationSession オブジェクトへの[メタデータ](https://docs.stripe.com/api.md#metadata)の追加がサポートされています。メタデータは顧客には表示されず、本人確認チェックの成否の要因としても考慮されません。

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

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

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

## セッションイベント

セッションのステータスが変化するたびに[イベント](https://docs.stripe.com/api/events.md)が作成されます。VerificationSession [イベントタイプ](https://docs.stripe.com/api.md#event_types)の全リストはこちらをご覧ください。

| イベントタイプ                                        | 説明                                                                                                                                                                                                                                               |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `identity.verification_session.created`        | セッションが[作成されました](https://docs.stripe.com/identity/verification-sessions.md#create)。                                                                                                                                                               |
| `identity.verification_session.processing`     | ユーザが情報を送信し、検証チェックは処理を開始しました。                                                                                                                                                                                                                     |
| `identity.verification_session.verified`       | すべての[本人確認チェック](https://docs.stripe.com/identity/verification-checks.md)の処理が完了し、確認のすべてが成功しました。                                                                                                                                                    |
| `identity.verification_session.requires_input` | すべての[本人確認チェック](https://docs.stripe.com/identity/verification-checks.md)の処理が完了し、少なくとも 1 つの確認が失敗しました。                                                                                                                                              |
| `identity.verification_session.canceled`       | セッションはキャンセルされ、今後の送信試行は無効化されました。このイベントは、セッションが[キャンセルされた](https://docs.stripe.com/identity/verification-sessions.md#cancel)場合、または[非表示にされた](https://docs.stripe.com/identity/verification-sessions.md#redact)場合に送信されます。                             |
| `identity.verification_session.redacted`       | セッションが[非表示](https://docs.stripe.com/identity/verification-sessions.md#redact)されました。このイベントタイプにアクセスするには、明示的に登録する [Webhook エンドポイント](https://docs.stripe.com/api/webhook_endpoints.md)を作成する必要があります。すべてのイベントに登録する Webhook エンドポイントには、このイベントタイプは含まれません。 |

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

Stripe では、[Webhook](https://docs.stripe.com/identity/handle-verification-outcomes.md) を使用してイベントをリッスンすることをお勧めします。

## See also

- [ユーザーの本人確認書類を確認する](https://docs.stripe.com/identity/verify-identity-documents.md)