Blog

Stripe Identity API 사용법: 개발자를 위한 신분증 확인 가이드

Ashley Innocent

Ashley Innocent

23 April 2026

Stripe Identity API 사용법: 개발자를 위한 신분증 확인 가이드

Apidog 엔터프라이즈

온프레미스 배포

SSO & RBAC

SOC 2 준수

Apidog Enterprise 살펴보기

사용자의 실제 신원을 확인하는 것은 화이트보드에서는 간단해 보이지만, 실제 구축을 시작하는 순간 몇 달이 걸리는 프로젝트로 변하는 작업 중 하나입니다. 문서 캡처, OCR, 얼굴 일치, 활성 감지, 사기 신호, 그리고 여러 국가에 걸친 수십 가지 ID 유형에 대한 지원이 필요합니다. Stripe Identity API는 이 모든 것을 단일 통합으로 패키징하여, 분기 단위가 아닌 단 하루 만에 프로덕션 준비가 된 신원 확인 흐름을 구축할 수 있도록 합니다.

이 가이드는 개발자가 Stripe Identity를 배포하는 데 필요한 모든 단계를 안내합니다. 대시보드에서 활성화하는 방법, VerificationSession을 생성하는 방법, 호스팅된 리디렉션과 임베디드 Stripe.js 컴포넌트 중에서 선택하는 방법, 웹훅을 처리하는 방법, 확인된 출력값을 읽는 방법 등이 포함됩니다. curl 및 Node 예제, 오류 처리 패턴, 그리고 Apidog를 사용하여 전체 흐름을 로컬에서 테스트하는 방법을 살펴보겠습니다. 다른 대안을 먼저 평가하고 있다면, 결정하기 전에 최고의 KYC API에 대한 저희의 요약 정보를 훑어보세요.

버튼

Stripe Identity는 이미 Stripe를 결제에 사용하는 팀에게 자연스럽게 잘 맞지만, 독립형 제품으로도 작동합니다. 공식 Stripe Identity 문서는 제품 표면을 다루며, 이 게시물은 개발자 경험의 공백을 채웁니다. 즉, 네트워크 상에서 어떤 일이 발생하는지, 어떤 필드가 중요한지, 그리고 일반적인 문제점들이 어디에 있는지 설명합니다.

요약 (TL;DR)

Stripe Identity API란 무엇인가요?

Stripe Identity는 Stripe의 핵심 API 기반 위에 구축된 신원 확인 제품입니다. 문서 캡처, 데이터 추출, 얼굴 매칭, 사기 점수 매기기를 조율하는 단일 엔드포인트 패밀리(/v1/identity/verification_sessions)를 제공합니다. 출력은 신뢰할 수 있는 서명되고 구조화된 기록입니다: 확인된 전체 이름, 생년월일, 주소, 그리고 선택적인 ID 번호가 Stripe 볼트에 저장된 원본 문서 이미지와 함께 제공됩니다.

내부적으로 Stripe는 Checkout 및 Payment Intents에서 이미 알고 있는 세션-플러스-웹훅 패턴을 사용합니다. 서버 측에서 세션을 생성하면 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는 두 가지 통합 형태를 제공합니다. 호스팅된 리디렉션은 가장 빠른 경로입니다. 사용자를 session.url로 보내면 Stripe가 stripe.com 도메인에서 전체 캡처 경험을 처리하고, 사용자는 return_url로 다시 돌아옵니다. 대략 10줄의 코드를 작성하면 됩니다.

임베디드 흐름은 Stripe.js와 @stripe/stripe-js 패키지를 사용하여 앱 내에 확인 모달을 마운트합니다. session.client_secret을 프런트엔드로 전달하고 stripe.verifyIdentity(clientSecret)를 호출합니다. 이는 사용자를 제품 내에 유지하고 주변 페이지에 대한 디자인 제어를 제공합니다. 회원가입 또는 KYC 단계에서 확인이 중간 흐름에서 발생하는 경우 이를 선택하고, 확인이 개별적인 작업인 경우 리디렉션을 선택하세요.

웹훅

클라이언트 리디렉션에 의존하여 확인이 성공했음을 알리지 마십시오. 항상 웹훅을 통해 백엔드에서 확인하십시오. 대시보드 > 개발자 > 웹훅에서 엔드포인트를 등록하고 다음을 구독하세요:

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"]를 사용하여 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는 라이브 모드에서 초당 100회 요청, 테스트 모드에서 초당 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.50달러입니다. 국제 가격은 다양하며, 대부분의 유럽 국가에서는 1.50~2.00달러 정도이며, Stripe는 가격 페이지에 전체 국가별 내역을 게시합니다. requires_input으로 끝나는 확인 시도는 청구 가능한 이벤트로 간주되지 않습니다. 완료된 verified 세션만 청구됩니다.

대량 고객의 경우, Stripe는 확인당 비용을 크게 절감할 수 있는 맞춤형 가격을 제공합니다. 한 달에 10,000건 이상의 확인을 처리하는 경우, 영업팀에 문의하세요.

Apidog로 Stripe Identity 테스트하기

API 플레이그라운드는 특히 웹훅 페이로드를 반복할 때 수동으로 curl 명령을 작성하는 것보다 항상 우수합니다. Apidog는 Stripe의 OpenAPI 사양을 직접 가져오므로, VerificationSession 객체의 모든 필드가 인라인 문서와 함께 표시됩니다. Stripe의 테스트 환경에 실제 요청을 보내고, 응답을 검사하고, 필요한 만큼 여러 번 재생할 수 있습니다.

웹훅 테스트 측면에서 Apidog는 가장 많은 시간을 절약해 줍니다. 실제 확인이 완료될 필요 없이 identity.verification_session.verified 이벤트를 로컬에서 모의하고, 개발 서버에 전송하고, 핸들러를 단계별로 실행할 수 있습니다. 워크플로우를 비교하고 있다면, 2026년 Postman 없이 API 테스트하기에 대한 저희 가이드에 더 깊이 있는 설명이 있습니다. 데스크톱 클라이언트를 받으려면 Apidog 다운로드.

자주 묻는 질문

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드