사용자의 실제 신원을 확인하는 일은 화이트보드 상에서는 단순하지만, 실제 구현에서는 문서 캡처, OCR, 얼굴 일치, 활성 감지, 수많은 국가별 ID 지원 등 복잡한 요소가 많아 빠르게 대규모 프로젝트로 발전할 수 있습니다. Stripe Identity API는 이런 모든 과정을 하나의 통합 API로 제공해, 하루 만에 프로덕션급 신원 확인 시스템을 구축할 수 있도록 지원합니다.
이 글에서는 Stripe Identity를 실제로 배포하는 데 필요한 모든 실질적 단계를 다룹니다. 대시보드 활성화, VerificationSession 생성, 리디렉션 vs 임베디드 Stripe.js 선택, 웹훅 처리, 검증 결과 읽기, curl/Node 예제, 에러 처리, 그리고 Apidog으로 전 과정 로컬 테스트하는 방법까지 포함합니다. 대안이 궁금하다면, 최고의 KYC API 요약도 참고하세요.
Stripe Identity는 Stripe 결제 유저에게 최적화되어 있지만, 독립형 신원 확인 API로도 사용할 수 있습니다. 이 글은 공식 Stripe 문서가 놓치기 쉬운, 네트워크 흐름, 필드 중요도, 실무적 문제점까지 실제 개발 관점에서 설명합니다.
요약 (TL;DR)
- Stripe Identity는 정부 발행 신분증+셀카 활성도 확인으로 사용자를 인증합니다. 미국 기준 건당 $1.50부터 시작.
- 핵심 객체는
VerificationSession입니다. 서버에서 생성 후, 리디렉션 또는 Stripe.js 컴포넌트로 연동. -
options.document.require_matching_selfie,require_id_number,allowed_types로 입력 필드 제어. -
identity.verification_session.verified,identity.verification_session.requires_input웹훅으로 상태 관리. - 확인된 값(이름, 생년월일, 주소, ID 번호 등)은
verified_outputs설정 시에만 노출. - 35개국 이상 지역화 문서 지원.
Stripe Identity API란?
Stripe Identity는 Stripe API 기반의 신원 확인 서비스입니다. 단일 엔드포인트(/v1/identity/verification_sessions)로 문서 캡처, 데이터 추출, 얼굴 매칭, 사기 분석까지 자동화합니다. 검증 결과는 신뢰할 수 있는 구조화 데이터(이름, 생년월일, 주소, ID 번호 등)와 원본 문서 이미지로 제공합니다.
구현 패턴은 Stripe Checkout/Payment Intents와 유사합니다. 서버에서 세션 생성 → Stripe가 사용자 캡처 UI 제공 → 확인 결과를 웹훅으로 수신하는 방식입니다. Stripe Checkout 경험이 있다면 빠르게 익숙해질 수 있습니다.
인증 및 설정
- 대시보드 > 설정 > Identity에서 Stripe Identity 활성화, 약관 동의 및 사업체 정보 입력
- Stripe 비밀 키(
sk_test_*또는sk_live_*) 사용. 별도 자격 증명 필요 없음 - Node SDK 설치
npm install stripe
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는 허용 문서 제한, verified_outputs는 반환 필드를 지정합니다. 데이터 최소화 및 규정 준수에 필수입니다.
호스팅 리디렉션 vs 임베디드 Stripe.js
호스팅 리디렉션: session.url을 프론트엔드에 전달해 Stripe 도메인에서 모든 확인 UI를 처리, 완료 후 return_url로 자동 복귀. 코드량 최소, 구현 속도 최우선.
임베디드 Stripe.js: @stripe/stripe-js로 앱 내부에서 확인 모달을 마운트. session.client_secret을 프론트로 전달 후 stripe.verifyIdentity(clientSecret) 호출. 중간 단계(회원가입, KYC) 플로우에 적합. 리디렉션이 싫거나 UI 제어가 필요하면 임베디드 선택.
웹훅
확인 성공/실패 등 결과는 반드시 웹훅으로 처리하세요. 대시보드 > 개발자 > 웹훅에서 엔드포인트 등록 후, 아래 이벤트를 구독합니다.
-
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 });
});
확인된 출력값 조회
웹훅에서는 민감 필드가 노출되지 않습니다. 검증 결과를 읽으려면 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는 1회만 반환되니 즉시 암호화/저장해야 합니다. 문서 이미지는 Stripe 볼트에 안전하게 저장, 대시보드에서만 감사를 위해 접근 가능합니다.
일반 오류 및 속도 제한
-
가장 자주 발생하는 실패는
document_unverified_other또는selfie_face_mismatch코드가 붙은verification_session.requires_input이벤트입니다. -> 사용자에게 재시도 UI 제공, 동일 세션 재사용(session.url), 또는 세션 취소 후 새 세션 생성 가능. -
API 속도 제한: 라이브 모드 초당 100회, 테스트 모드 초당 25회
->
HTTP 429및Retry-After헤더 발생 시 지수 백오프 적용. -
기타 오류:
unsupported_document_type(허용되지 않은 ID 업로드),country_not_supported(지원 국가 외 문서)
Stripe Identity 가격
- 미국 기준 건당 $1.50, 유럽 다수 국가는 $1.50~2.00, 국가별 가격은 Stripe 가격 페이지 참고
-
requires_input로 종료된 시도는 과금 대상 아님.verified만 청구 - 월 10,000건 이상 대량 고객은 개별 할인 협의 가능
Apidog로 Stripe Identity 테스트하기
API 플레이그라운드는 curl 수동 작성보다 효율적입니다. Apidog는 Stripe의 OpenAPI 사양을 바로 불러와 VerificationSession의 모든 필드를 인라인 문서와 함께 확인할 수 있습니다. 실제 Stripe 테스트 환경에 요청/응답을 반복하며, 다양한 케이스를 빠르게 검증할 수 있습니다.
특히 웹훅 테스트에서 Apidog의 생산성이 높습니다. 실제 검증 없이 identity.verification_session.verified 이벤트를 로컬에서 모의, 개발 서버로 전송, 핸들러 로직을 단계별로 검증할 수 있습니다.
Postman 대체 워크플로우 참고: 2026년 Postman 없이 API 테스트하기
데스크톱 클라이언트: Apidog 다운로드
자주 묻는 질문
- Stripe Identity와 Stripe의 일반 KYC의 차이점? Stripe의 내장 KYC는 Connect/Payments 사업주 신원 확인, Stripe Identity는 최종 사용자 확인용 독립 API. 두 시스템 결과는 공유되지 않음.
-
여러 세션에서 확인된 신원을 재사용할 수 있나요?
네. 세션 검증 완료 시
verified_outputs가 영구 저장됩니다. 새로운 이벤트에는 새 세션을 생성해 연결하세요. - Stripe Identity는 결제 없이도 사용 가능한가요? 가능. 결제 기능 없이 KYC 계층으로만 활용하는 고객도 많음. 제재 심사 등 추가 심사가 필요하면 AML 심사 API와 조합 추천.
- Stripe Identity vs Plaid Identity Verification? Stripe는 문서+셀카 중심, Plaid는 은행 확인 신원 데이터 기반. 자세한 비교는 Plaid API 가이드 참고.
-
셀카 활성도 확인이 필수인가요?
아닙니다. 문서 기반만 필요하다면
require_matching_selfie를false로 설정. 하지만 사기 방지상 활성도 확인을 권장. - Stripe Identity 지원 국가는? 북미, 유럽, 아시아 태평양 일부 포함 35개국 이상. 각국에 맞는 문서 파싱, 국가 목록은 Stripe 공식 문서에서 실시간 확인 가능.
Top comments (0)