Akira

Posted on Apr 23 • Originally published at apidog.com

Stripe Identity API の使い方：ID検証デベロッパーガイド

ユーザーの現実世界の身元確認は、一見シンプルですが、実装すると多くの工数がかかります。書類のキャプチャ、OCR、顔認証、生体検知、不正信号、そして複数国のIDタイプ対応まで、課題は多岐にわたります。Stripe Identity APIを使えば、これらを一つの統合APIで処理し、数ヶ月規模の開発を数時間で本番投入レベルに引き上げることが可能です。

Apidogを今すぐ試す

本ガイドでは、Stripe Identity導入に必要な実装手順を順序立てて解説します。ダッシュボードでの有効化からVerificationSessionの作成、ホスト型リダイレクトとStripe.js組み込み型の選択、Webhook管理、検証済み出力の取得までをカバー。curlやNodeサンプル、エラーハンドリング、Apidogを使ったローカルテストのやり方も紹介。まずは他の選択肢を検討中なら、最高のKYC APIまとめも確認してみてください。

Stripe Identityは、既にStripe決済を利用しているチームにはもちろん、単体KYCとしても利用可能です。公式ドキュメントは概要中心なので、本記事では開発者視点で「何がどう動くか」「落とし穴」まで具体的に掘り下げます。

TL;DR

Stripe Identityは政府発行ID＋セルフィーによる生体認証でユーザーを検証。米国では1.50ドル/1認証から。
主要オブジェクトはVerificationSession。サーバーで作成→リダイレクト or Stripe.jsマウント。
options.document.require_matching_selfie、require_id_number、allowed_typesで制御。
状態管理はidentity.verification_session.verifiedとidentity.verification_session.requires_inputのWebhookで。
検証済み出力（氏名・生年月日等）はverified_outputs指定時のみ取得可能。
35カ国以上のローカライズ書類サポート。

Stripe Identity APIとは？

Stripe IdentityはStripe API上に構築された本人確認サービス。書類キャプチャ、データ抽出、顔照合、不正検知を一つの/v1/identity/verification_sessionsファミリーで実行。出力は検証済み氏名、生年月日、住所、ID番号（オプション）と、元書類画像（Stripe内ボールト保管）。

内部的にはセッション＋Webhook方式（Checkout等と同じ）。サーバーでセッション作成→Stripe側でUI表示→結果Webhook通知。Checkout経験者ならすぐ実装可能です。

認証とセットアップ

ダッシュボードでStripe Identityを有効化（設定 > Identity）。利用規約同意＆事業者情報入力で準備完了。テスト・本番両方で有効。
API認証は既存のStripeシークレットキー（sk_test_またはsk_live_）。追加資格情報不要。
Node SDKインストール:
```
npm install stripe
```

クライアント初期化（APIバージョン固定推奨）:

import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: "2024-06-20",
});

これでstripe.identity.verificationSessionsを操作可能です。

主要エンドポイント

VerificationSessionの作成

ユーザーごとにVerificationSessionを新規作成。書類種別・セルフィー要否・返却フィールドを細かく設定可能。

curl例:

curl https://api.stripe.com/v1/identity/verification_sessions \
  -u "$STRIPE_SECRET_KEY:" \
  -d "type=document" \
  -d "options[document][require_matching_selfie]=true" \
  -d "options[document][require_id_number]=true" \
  -d "options[document][allowed_types][]=driving_license" \
  -d "options[document][allowed_types][]=passport" \
  -d "verified_outputs[]=first_name" \
  -d "verified_outputs[]=last_name" \
  -d "verified_outputs[]=dob" \
  -d "verified_outputs[]=address" \
  -d "verified_outputs[]=id_number" \
  -d "metadata[user_id]=usr_7f3k2"

Node SDK例:

const session = await stripe.identity.verificationSessions.create({
  type: "document",
  options: {
    document: {
      require_matching_selfie: true,
      require_id_number: true,
      allowed_types: ["driving_license", "passport", "id_card"],
    },
  },
  verified_outputs: [
    "first_name",
    "last_name",
    "dob",
    "address",
    "id_number",
  ],
  metadata: { user_id: "usr_7f3k2" },
});

// クライアントに返す値（どちらか選択）
// session.url           → ホスト型リダイレクト
// session.client_secret → Stripe.js組み込み

ポイント:

type: "document"は書類チェック指定。
allowed_typesで受入書類種別制限（例：顔写真付きIDのみ）。
verified_outputsは返却してほしいフィールドを明示（データ最小化）。

ホスト型リダイレクト vs 組み込み型Stripe.js

ホスト型リダイレクト: session.urlにユーザーをリダイレクト。Stripe側でUI全処理後、return_urlに戻す。最速＆シンプル。
組み込み型: session.client_secretをフロントに渡し、Stripe.jsでstripe.verifyIdentity(clientSecret)を呼ぶ。自社サービス内で完結したUXが構築可能。

サインアップやKYC途中で本人確認が必要→組み込み型。独立タスクならリダイレクト型が最短。

Webhook

クライアントのリダイレクト先で認証結果を信用せず、必ずバックエンドでWebhookを受信して状態管理しましょう。設定手順:

ダッシュボード > 開発者 > Webhookでエンドポイント追加。
以下イベントを購読:
- identity.verification_session.verified: 認証成功・検証済みデータ準備完了時
- identity.verification_session.requires_input: 失敗・再入力要求時
- identity.verification_session.processing: Stripe側で非同期チェック中
- identity.verification_session.canceled: セッションキャンセル時

サンプル実装（Node/Express）:

app.post("/webhooks/stripe", express.raw({ type: "application/json" }), async (req, res) => {
  const event = stripe.webhooks.constructEvent(
    req.body,
    req.headers["stripe-signature"],
    process.env.STRIPE_WEBHOOK_SECRET
  );

  if (event.type === "identity.verification_session.verified") {
    const session = event.data.object;
    await markUserVerified(session.metadata.user_id, session.id);
  }

  if (event.type === "identity.verification_session.requires_input") {
    await notifyUserToRetry(event.data.object.metadata.user_id);
  }

  res.json({ received: true });
});

検証済み出力の取得

Webhookでは検証結果「通知」のみ。実データはexpand: ["verified_outputs"]指定で取得します。

const session = await stripe.identity.verificationSessions.retrieve(
  "vs_1N...",
  { expand: ["verified_outputs"] }
);

const { first_name, last_name, dob, address, id_number } = session.verified_outputs;

id_numberは一度だけ返却なので即時暗号化保存推奨。書類画像はStripeボールト保管、ダッシュボードで閲覧可能。

一般的なエラーとレート制限

document_unverified_otherやselfie_face_mismatch等の失敗コードはverification_session.requires_inputで通知。UIで再試行案内を実装。
同一セッションはverificationSessions.cancel後に新規作成も可能。未完了なら再リダイレクトで再利用も可。
APIレート制限: ライブ100req/sec、テスト25req/sec（全Stripe API共通バケット）。429時はRetry-Afterヘッダー遵守＆指数バックオフ。
unsupported_document_type（受入不可ID）、country_not_supported（未対応国）エラーも要注意。

Stripe Identityの料金

米国: 1.50ドル/認証（国際料金は国別で異なる。ヨーロッパ1.50〜2.00ドル程度）。
requires_inputで終わった試行は課金対象外。完了したverifiedのみ課金。
大量利用（1万件/月〜）はカスタム料金応相談。

ApidogでのStripe Identityのテスト

APIプレイグラウンド活用で開発効率UP。ApidogはStripe OpenAPI仕様を直接インポート可能。VerificationSessionの全フィールドがインラインドキュメント化され、テスト環境でリクエスト実行・レスポンス検証・再生が容易。

Webhookのテストは特に有用。identity.verification_session.verifiedイベントをローカルでモック送信し、実際の認証待ち不要でハンドラーデバッグが可能です。Postman比較など詳細は2026年のAPIテストガイド参照。Apidogデスクトップクライアントを入手して試しましょう。

よくある質問

Stripe IdentityとStripeの通常のKYCの違いは？ Stripe標準KYCはConnect/Paymentsの事業主検証用。Stripe Identityはエンドユーザー検証用スタンドアロンAPIで、両者の結果は連動しません。

検証済みIDを他セッションでも再利用できる？ 可能。verified_outputsはセッション上で永続化。新イベントごとに新規セッション作成＆自ユーザーIDに紐付け推奨。

Stripe Identityは決済機能なしでも利用可能？ もちろんOK。KYC専用用途の導入事例多数。制裁スクリーニングも必要なら、AMLスクリーニングAPIも活用可能。

Stripe IdentityとPlaid Identity Verificationの違いは？ Stripeは書類＋セルフィー重視。Plaidは銀行ベースIDデータ重視。詳細はPlaid APIガイド参照。

セルフィー必須？ 必要なければoptions.document.require_matching_selfie: falseで書類チェックのみも可。不正対策目的ならセルフィー有効推奨。

対応国は？ 北米・欧州・アジア太平洋の一部など35カ国超で、国別に最適化された書類パーサーを持ち、対応国は随時拡大中。

DEV Community