ユーザーの現実世界の身元を確認する作業は、ホワイトボード上ではシンプルに見えますが、構築を始めるとすぐに数ヶ月にわたるプロジェクトになります。書類のキャプチャ、OCR、顔認証、生体検知、不正信号、そして数十種類の国別IDタイプに対応する必要があります。Stripe Identity APIはこれらすべてを単一の統合にまとめ、四半期ではなく午後のうちに本番環境対応のID認証フローを立ち上げることができます。
このガイドでは、開発者がStripe Identityを導入するために必要なすべてのステップを説明します。ダッシュボードでの有効化、VerificationSessionの作成、ホスト型リダイレクトと組み込み型Stripe.jsコンポーネントの選択、Webhookの処理、そして検証済み出力の読み取りなどです。curlとNodeの例、エラー処理パターン、そしてApidogを使ってローカルでフロー全体をテストする方法も紹介します。まず代替案を検討している場合は、コミットする前に最高のKYC APIのまとめをざっと読んでみてください。
Stripe Identityは、すでにStripeを決済に利用しているチームには自然に適合しますが、単体製品としても機能します。公式のStripe Identityドキュメントは製品の表面をカバーしていますが、この投稿では開発者体験のギャップを埋めるものです。具体的には、ワイヤー上で何が起こるか、どのフィールドが重要か、そして一般的な落とし穴はどこにあるかなどです。
TL;DR
- Stripe Identityは、政府発行のIDとセルフィーによる生体チェックでユーザーを認証します。料金は米国では1回の認証につき1.50ドルから。
- コアとなるプリミティブは`VerificationSession`オブジェクトです。サーバーサイドでこれを作成し、その後ユーザーをリダイレクトするか、Stripe.jsコンポーネントをマウントします。
- 必要なフィールドは`options.document.require_matching_selfie`、`require_id_number`、`allowed_types`を通じてリクエストします。
- アプリの状態を駆動するために、`identity.verification_session.verified`と`identity.verification_session.requires_input`のWebhookをリッスンします。
- 検証済み出力（氏名、生年月日、住所、ID番号）は、セッション作成時に`verified_outputs`を設定した場合にのみ公開されます。
- Stripe Identityは、ローカライズされた書類サポートにより35カ国以上に対応しています。
Stripe Identity APIとは？
Stripe Identityは、StripeのコアAPIの上に構築されたID認証製品です。これは、書類のキャプチャ、データ抽出、顔照合、不正スコアリングをオーケストレーションする単一のエンドポイントファミリ（`/v1/identity/verification_sessions`）を提供します。出力は、信頼できる署名済みの構造化された記録です。具体的には、検証済みの氏名、生年月日、住所、およびオプションのID番号であり、Stripeのボールトに保存された元の書類画像とペアになっています。
内部的には、StripeはCheckoutやPayment Intentsですでに知られているセッション+Webhookのパターンを使用します。サーバーサイドでセッションを作成し、Stripeがユーザー向けのキャプチャUIを処理し、結果が準備できたときに通知を受け取ります。以前にCheckoutフローを構築したことがある場合、Identityは数分で馴染み深く感じるでしょう。
認証とセットアップ
APIを呼び出す前に、ダッシュボードでStripe Identityを有効にしてください。ダッシュボード > 設定 > Identityに移動し、規約に同意し、StripeがKYCコンプライアンスのために必要とするビジネス詳細を入力します。このトグルは、アカウントのテストモードとライブモードの両方でIdentityを有効にします。
認証には標準のStripeシークレットキーを使用します。テストキーは`sk_test_`で始まり、ライブキーは`sk_live_`で始まります。Stripe Identityは個別の資格情報を必要としないため、統合の範囲を小さく保つことができます。
Node SDKをインストールします:
npm install stripe
次に、クライアントを初期化します。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" },
});
// Send one of these to the client:
// session.url -> hosted redirect
// session.client_secret -> Stripe.js embedded component
いくつかのフィールドに注意が必要です。`type: "document"`はStripeに書類チェックを実行するよう指示します。代替の`id_number`は、IDを収集せずに米国限定のSSNスタイルのルックアップを行います。`allowed_types`はユーザーがアップロードできる書類カテゴリを制限し、政府発行の顔写真付きIDのみを受け入れるコンプライアンスプログラムにとって重要です。`verified_outputs`は返してほしいフィールドの許可リストです。Stripeは要求しなかったデータを公開しないため、データ最小化の姿勢を清潔に保つことができます。
ホスト型認証リダイレクト vs. 組み込み型Stripe.js
Stripeは2つの統合形式を提供します。ホスト型リダイレクトは最速のパスです。ユーザーを`session.url`に送信すると、Stripeがstripe.comドメインでキャプチャ体験全体を処理し、ユーザーは`return_url`に戻されます。コードは概ね10行程度で済みます。
組み込み型フローは、Stripe.jsと`@stripe/stripe-js`パッケージを使用して、自分のアプリ内に認証モーダルをマウントします。`session.client_secret`をフロントエンドに渡し、`stripe.verifyIdentity(clientSecret)`を呼び出します。これにより、ユーザーはあなたの製品内に留まり、周囲のページの設計を自由に制御できます。サインアップやKYCステップの途中で認証が行われる場合にこれを選択し、認証が独立したタスクである場合はリダイレクトを選択してください。
Webhook
認証が成功したことをクライアントリダイレクトに頼ることは決してしないでください。常にWebhookを介してバックエンドで確認してください。ダッシュボード > 開発者 > Webhookでエンドポイントを登録し、以下を購読します。
- `identity.verification_session.verified`は、すべてのチェックが合格し、検証済みデータが準備できたときに発火します。
- `identity.verification_session.requires_input`は、ユーザーがチェックに失敗した場合や読み取れない書類をアップロードした場合に発火します。彼らをリダイレクトして再試行させることができます。
- `identity.verification_session.processing`は、Stripeが非同期チェックを実行中に発火します。スピナーの状態を表示するのに役立ちます。
- `identity.verification_session.canceled`は、プログラムによってセッションをキャンセルした場合に発火します。
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"]`を指定して`verificationSessions.retrieve`を呼び出します。
const session = await stripe.identity.verificationSessions.retrieve(
"vs_1N...",
{ expand: ["verified_outputs"] }
);
const { first_name, last_name, dob, address, id_number } = session.verified_outputs;
Stripeは`id_number`を一度だけ返します。すぐにあなたの側で暗号化して保存してください。書類画像自体はStripeのボールトに残り、監査のためにダッシュボードからアクセスできます。
一般的なエラーとレート制限
最も頻繁に発生する失敗は、`document_unverified_other`や`selfie_face_mismatch`のようなコードを伴う`verification_session.requires_input`です。これらは、ユーザーフレンドリーな再試行UIを表示することで処理します。同じセッションは、`verificationSessions.cancel`を呼び出して新しいセッションを作成するか、まだ開いている間に同じ`session.url`にリダイレクトすることで再利用できます。
Stripeは、ライブモードで1秒あたり100リクエスト、テストモードで1秒あたり25リクエストの標準APIレート制限を適用します。`/identity/verification_sessions`エンドポイントは、他のAPIと同じバケットに分類されます。制限に達した場合、`Retry-After`ヘッダー付きのHTTP 429が表示されます。指数バックオフを使用し、ヘッダーを尊重してください。
その他、注意すべきエラーとして、ユーザーが`allowed_types`リスト外のIDをアップロードした際の`unsupported_document_type`、そしてStripe Identityがまだ対応していない国の書類を試した場合の`country_not_supported`があります。
Stripe Identityの料金
Stripe Identityは、米国では1回の認証につき1.50ドルかかります。国際料金は異なります。ほとんどのヨーロッパ諸国では1.50ドルから2.00ドル程度で、Stripeはその料金ページで国別の詳細を公開しています。`requires_input`で終了した認証試行は課金対象のイベントとはみなされません。完了した`verified`セッションのみが課金されます。
大量に利用する顧客向けには、Stripeはチェックごとの料金を大幅に削減できるカスタム料金を提供しています。月に10,000回以上の認証を処理する場合は、営業担当にご相談ください。
ApidogでのStripe Identityのテスト
特にWebhookペイロードを反復処理する場合、APIプレイグラウンドは手動でcurlコマンドを作成するよりも常に優れています。ApidogはStripeのOpenAPI仕様を直接インポートするため、`VerificationSession`オブジェクトのすべてのフィールドがインラインドキュメント付きで表示されます。Stripeのテスト環境で実際の要求を送信し、応答を検査し、必要に応じて何度でも再生できます。
Webhookテストの側面こそ、Apidogが最も時間を節約できる部分です。`identity.verification_session.verified`イベントをローカルでモックし、開発サーバーに送信し、実際の認証が完了するのを待たずにハンドラーをステップ実行できます。ワークフローを比較している場合は、2026年のPostmanなしでのAPIテストに関するガイドで詳細なウォークスルーをご覧いただけます。Apidogをダウンロードしてデスクトップクライアントを入手してください。
よくある質問
Stripe IdentityとStripeの通常のKYCの違いは何ですか？ Stripeの組み込みKYCは、ConnectおよびPaymentsアカウントの事業主を検証します。Stripe Identityは、エンドユーザーを検証するためのスタンドアロンAPIであり、これら2つのシステムは検証結果を共有しません。
検証済みのIDを複数のセッションで再利用できますか？ はい、できます。セッションが検証されると、`verified_outputs`はそのセッションオブジェクト上で永続的になります。新しいイベントのために再検証が必要な場合は、新しいセッションを作成し、それをあなたの側のユーザーレコードにリンクしてください。
Stripe Identityは決済以外でも機能しますか？ はい、もちろんです。多くのお客様は、純粋にKYCレイヤーとして使用しており、Stripeの決済機能を一切利用していません。ID認証に加えてより広範な制裁スクリーニングが必要な場合は、専用のAMLスクリーニングAPIと組み合わせてください。
Stripe IdentityとPlaid Identity Verificationの比較は？ Stripeは書類とセルフィーに焦点を当てています。Plaidは銀行で検証されたIDデータに重点を置いています。別の方法については、私たちのPlaid APIガイドを参照してください。
セルフィーによる生体確認は必須ですか？ いいえ。書類チェックのみが必要な場合は、`options.document.require_matching_selfie`を`false`に設定してください。ほとんどの不正対策チームは、受動的な生体確認が多くの低レベルな攻撃を捕捉するため、これを有効にしています。
Stripe Identityはどの国に対応していますか？ 北米、ヨーロッパ、アジア太平洋地域の一部を含む35カ国以上に対応しており、それぞれの国に合わせた書類パーサーが用意されています。Stripeは、対応国リストをドキュメントで公開し、定期的に新しい市場を追加しています。