본인인증은 휴대폰(통신사) 또는 PASS 앱으로 사용자가 본인임을 확인하고, 이름·생년월일·성별·내외국인·통신사와 CI/DI 같은 식별값을 받아오는 기능이에요. 회원가입 실명 확인, 성인 콘텐츠 인증, 명의 도용 방지, 고액 결제 전 본인 확인 등에 사용해요.
본인인증은 돈이 오가는 결제가 아니라 신원 확인만 수행해요. 결제 직전 본인 확인이 필요하면 본인인증을 먼저 끝내고, 그 결과(CI/DI)를 결제·회원 흐름과 연결해요.
무엇을 받을 수 있나
인증이 완료되면 authenticate_data로 아래 값을 받아요.
| 필드 | 설명 |
|---|---|
name |
인증된 실명 |
phone |
인증에 사용한 휴대폰번호 |
birth |
생년월일 |
gender |
성별. Integer — 0 여성, 1 남성 |
foreigner |
내외국인 여부. PG마다 타입이 달라요 — 다날은 PG 원본 문자열("0" 내국인 / "1" 외국인), KCP는 Integer(0 / 1)로 변환돼서 전달돼요 |
carrier |
통신사. String — SKT / KT / LGT 등 |
unique |
CI — 사용자별 고유 식별값(연계정보). 같은 사람이면 어느 가맹점에서 인증해도 같은 값 |
di |
DI — 가맹점(사이트)별 고유 식별값(중복가입 확인정보). 같은 사람이라도 가맹점마다 다른 값 |
tid |
PG사 거래 고유 ID |
- CI는 어느 서비스에서 인증해도 동일하므로, 같은 사람을 식별하거나 타 서비스와 연계할 때 사용해요. (88byte 고유값)
- DI는 우리 서비스 안에서만 동일하므로, 중복 가입 방지에 사용해요.
- 두 값 모두 개인정보이므로 암호화 저장하고, 외부에 노출하지 않아요.
두 가지 연동 방식
본인인증은 목적에 따라 두 가지로 연동해요.
| 방식 | 화면 구성 | 언제 쓰나 | 문서 |
|---|---|---|---|
| SDK 본인인증 | PG가 제공하는 인증창 UI를 그대로 사용 | 가장 일반적. 프론트에서 requestAuthentication()만 호출하면 통신사 선택·OTP 입력 화면까지 PG가 처리 |
SDK 본인인증 |
| REST API 본인인증 | 인증 UI를 가맹점이 직접 구성 | 자체 디자인의 입력 폼이 필요하거나, 서버가 SMS/PASS 발송·검증을 직접 통제해야 할 때 | REST API 본인인증 |
대부분은 SDK 본인인증으로 충분해요. 인증창 화면을 직접 만들고 OTP 발송·재전송·검증을 단계별로 제어해야 하는 경우에만 REST API 본인인증을 사용해요.
전체 흐름
본인인증 요청
SDK 방식은 프론트에서 requestAuthentication()을, REST 방식은 서버에서 POST /v2/request/authentication을 호출해요.
사용자 인증
사용자가 통신사 선택 → 정보 입력 → SMS OTP 또는 PASS 앱으로 인증을 완료해요.
결과 수신
SDK 방식은 done 이벤트로 receipt_id를 받고, REST 방식은 OTP 검증(confirm) 응답으로 authenticate_data를 받아요.
결과 검증 (필수)
SDK 방식에서 받은 결과는 위변조될 수 있으므로, 서버에서 GET /v2/certificate/{receipt_id}로 다시 조회해 authenticate_data를 확정해요.
결제 검증과 마찬가지로, 프론트엔드에서 받은 본인인증 결과만 믿고 회원 실명·성인 여부를 확정하면 안 돼요. 반드시 서버에서 receipt_id로 결과 조회 API를 호출해 확인해요.
본인인증 상태값
| status | 의미 | 설명 |
|---|---|---|
50 |
본인인증준비 | 인증 요청이 막 생성된 내부 초기 상태 |
51 |
본인인증승인전 | SMS/PASS 발송 완료, OTP 검증(승인) 대기 상태 |
12 |
본인인증완료 | 인증이 완료되어 authenticate_data를 받을 수 있는 상태 |
-50 |
본인인증실패 | 인증 요청·발송 단계에서 실패한 상태 |
-12 |
본인인증승인오류 | OTP 승인 단계에서 실패한 상태 |
50은 요청 처리 중에만 잠깐 머무는 내부 초기 상태라, 요청 API 응답에서는 발송까지 끝난51로 관측돼요.- 한글 상태 라벨은
12(본인인증완료)에만 정의돼 있어요.50·51·-50·-12상태에서는status_locale키 자체가 응답에서 빠져요. 응답에status_locale이 있다고 가정하고 파싱하면 안 돼요.
준비물
- 본인인증 가능한 PG 계약 (예: 다날). 관리자 콘솔에서 본인인증 PG를 활성화해요.
- 백엔드 연동키(Client Key / Secret Key). 결과 조회·REST 인증은 서버에서 Basic Auth로 호출해요.
다음 단계
- 인증창 UI를 PG에 맡기는 일반 연동은 SDK 본인인증을 확인해요.
- 인증 화면을 직접 만들고 OTP를 단계별로 제어하려면 REST API 본인인증을 확인해요.