본인확인

본인확인 서비스(ver. V2) 연동하기

NHN KCP 본인확인 V2 서비스는 고객이 본인확인 화면에서 인증을 완료하면 인증 결과를 가맹점으로 전달하는 서비스입니다.
가맹점은 전달받은 결과를 조회하고 복호화하여 고객 본인 여부를 확인합니다.

본인확인 서비스 과정

본인확인 서버 IP 정보

안정적인 서비스 이용을 위해 도메인 기반 통신을 권장합니다.
IP 기준으로 화이트리스트를 관리하는 가맹점은 서버 방화벽 정보에 기재된 IP를 모두 허용해야 합니다.

구분	테스트	운영
URL	testcert.kcp.co.kr	cert.kcp.co.kr
IP	210.122.176.55	211.36.208.10, 210.122.74.20
PORT	443	443
연결방향	INBOUND/OUTBOUND	INBOUND/OUTBOUND

ENC_KEY 발급 및 관리 유의사항

ENC_KEY는 본인확인 거래등록과 결과 조회 시 사용합니다. 가맹점만 요청 데이터를 생성하고 해석할 수 있도록 하여,
가맹점 식별과 데이터 위·변조 방지에 사용됩니다.

ENC_KEY 발급경로

파트너관리자 로그인 → 기술관리센터 → 인증센터 → 가맹점 인증키 관리

실제 가맹점 정보로 연동하는 경우, 인증키가 발급 및 적용되지 않은 상태에서는 서비스를 이용할 수 없습니다. 반드시 파트너관리자에서 인증키 발급을 완료한 뒤 가맹점 소스에 적용해야 합니다. 테스트용으로 제공되는 정보는 인증키가 사전에 발급되어 있어 별도 발급 요청 없이 사용할 수 있습니다.

1. Header 설정하기

Header는 본인확인 거래등록과 결과 조회 API를 호출할 때 함께 전달하는 인증 정보입니다.
NHN KCP는 Header 값을 기준으로 가맹점과 요청 데이터를 확인합니다.

요청 데이터 예시

Content-Type : application/json
site_cd : AO7F3
rv   : Q2hhbmd1VGh......HQ=

Header 설정 값

site_cd 필수 PC / Mobile string5

영문 대문자 또는 영문 대문자와 숫자로 구성된 사이트 코드입니다. NHN KCP의 모든 서비스에서 가맹점을 구분할 때 사용합니다.※ 해당 값은 본인확인 거래등록과 본인확인 결과 조회에서 사용합니다.ex) "site_cd" : "AO7F3"

rv 필수 PC / Mobile string16

암호화에 사용하는 랜덤 값을 Base64 방식으로 인코딩한 값입니다.※ 해당 값은 본인확인 거래등록에서만 사용하며, 본인확인 결과 조회에서는 사용하지 않습니다.※ rv 값 생성 방법은 하단의 암호화 데이터 처리를 참고합니다.

암호화 데이터 처리

가맹점에서 생성한 JSON 데이터를 NHN KCP가 제공하는 라이브러리의 encryptJson 함수로 암호화하여 enc_data와 rv 값을 생성합니다. 생성된 값은 거래등록 API를 호출할 때 사용합니다.

예시) enc_data, rv = encryptJson(json_text, enc_key, site_cd)

2. 거래 등록 하기

본인확인 거래등록은 고객에게 본인확인 화면을 보여주기 전에 인증 URL과 거래등록키를 먼저 발급받는 단계입니다.

거래등록이 완료되면 NHN KCP에서 본인확인 화면 호출과 결과 조회에 필요한 reg_cert_key와 call_url을 응답합니다.
call_url은 본인확인 화면 호출에 사용하므로 거래등록 후 응답받은 값을 그대로 사용하세요.
reg_cert_key는 본인확인창 호출과 본인확인 결과 조회에 사용하므로 가맹점 서버에 저장하여 관리하세요.

거래등록 요청과 응답 파라미터는 API Reference > 본인확인 거래등록을 확인하세요.

3. 본인확인창 호출하기

본인확인 인증창은 PC 환경에서는 팝업 방식으로, Mobile 환경에서는 페이지 전환 방식으로 호출합니다.
거래등록 응답으로 받은 call_url에 파라미터를 form 형태로 전달하여 본인확인 인증창을 호출합니다.

본인확인창 호출 함수

function () {
  var auth_form = document.form_auth;
  auth_form.action = auth_form.call_url.value;

  if (auth_form.kcp_page_submit_yn.value === "N") {
    var width  = 410;
    var height = 500;
    var left   = (screen.width  / 2) - (width  / 2);
    var top    = (screen.height / 2) - (height / 2);

    var opts = "width=" + width + ",height=" + height
             + ",toolbar=no,status=no,menubar=no,scrollbars=no,resizable=no"
             + ",left=" + left + ",top=" + top;

    window.open("", "auth_popup", opts);
    auth_form.target = "auth_popup";
  } else {
    auth_form.target = "_self";
  }
  auth_form.submit();
}

본인확인창 호출 파라미터

reg_cert_key 필수 PC / Mobile string20

거래등록 후 응답받은 거래등록키입니다. 본인확인창 호출과 본인확인 결과 조회에 사용합니다.※ 인증 성공 후 바로 본인확인 결과 조회를 진행합니다.ex) "reg_cert_key" : "1234567890123456"

kcp_page_submit_yn 필수 PC / Mobile string1

본인확인 인증창을 호출하는 방식을 설정합니다.
Y : 페이지 전환 방식으로 호출합니다. Mobile 환경에서 사용합니다.
N : 팝업 방식으로 호출합니다.ex) "kcp_page_submit_yn" : "Y"

4. 본인확인창 인증 결과

고객의 본인확인 인증이 완료되면 인증 처리 결과가 Ret_URL을 통해 가맹점으로 전달됩니다.
정상 인증 결과(res_cd=0000)를 받은 뒤에는 반드시 본인확인 결과 조회까지 진행하세요.

본인확인 결과 조회를 진행하지 않으면 고객 정보를 확인할 수 없습니다.

본인확인 인증 결과 파라미터

res_cd PC / Mobile string4

결과 코드입니다. 인증이 정상 처리되면 0000이 응답됩니다.ex) "res_cd" : "0000"

res_msg PC / Mobile string100

결과 메시지입니다.ex) "res_msg" : "정상처리"

reg_cert_key PC / Mobile string20

거래등록 후 응답받은 거래등록키입니다.
인증 결과 Callback으로 전달된 reg_cert_key는 가맹점 DB에 저장된 거래등록키와 주문번호가 일치하는지 확인한 뒤 사용합니다.

param_opt_1 Mobile string1000

NHN KCP 기본 파라미터 외에 가맹점이 추가로 사용할 수 있는 파라미터입니다.ex) "param_opt_1" : "test"

param_opt_2 Mobile string1000

NHN KCP 기본 파라미터 외에 가맹점이 추가로 사용할 수 있는 파라미터입니다.ex) "param_opt_2" : "test"

param_opt_3 Mobile string1000

NHN KCP 기본 파라미터 외에 가맹점이 추가로 사용할 수 있는 파라미터입니다.ex) "param_opt_3" : "test"

5. 본인확인 결과 조회하기

가맹점 Ret_URL로 응답받은 인증 결과가 정상인 경우, 가맹점 서버에서 NHN KCP로 본인확인 결과 조회를 요청합니다.
본인확인 결과 조회를 통해 암호화된 고객 인증 데이터를 응답받습니다.
이후 가맹점 서버에서 암호화된 데이터를 복호화하여 CI, DI, 이름 등 인증이 완료된 고객 정보를 확인합니다.

본인확인 결과 조회 요청 전문은 암호화하지 않은 평문 JSON 형태로 전송합니다.

본인확인 결과조회 요청과 응답 파라미터는 API Reference > 본인확인 결과조회를 확인하세요.

6. 본인확인 결과 복호화

본인확인 결과 조회로 응답받은 암호화 인증 데이터(enc_cert_data, rv)를 NHN KCP가 제공하는 라이브러리의 decryptJson 함수로 복호화합니다. 복호화가 완료되면 고객 인증 정보가 포함된 dec_data를 확인합니다.

예시) dec_data = decryptJson(enc_cert_data, rv, ENC_KEY, SITE_CD)

본인확인 결과 복호화 파라미터

res_cd PC / Mobile string4

결과 코드입니다. 인증이 정상 처리되면 0000이 응답됩니다.ex) "res_cd" : "0000"

res_msg PC / Mobile string100

결과 메시지입니다. 정상 처리된 경우 정상처리가 응답됩니다.ex) "res_msg" : "정상처리"

phone_no PC / Mobile string11

본인확인에 사용한 휴대폰 번호입니다. 하이픈(-) 없이 숫자만 응답됩니다.ex) "phone_no" : "01012341234"

user_name PC / Mobile string60

본인확인을 완료한 고객의 이름입니다.ex) "user_name" : "홍길동"

birth_day PC / Mobile string8

고객의 생년월일입니다. YYYYMMDD 형식으로 응답됩니다.ex) "birth_day" : "19900101"

comm_id PC / Mobile string3

고객이 본인확인에 사용한 이동통신사 코드입니다.
SK텔레콤 : SKT
LG U+ : LGT
KT : KTF
SKT 알뜰폰 : SKM
LG U+ 알뜰폰 : LGM
KT 알뜰폰 : KTMex) "comm_id" : "KTF"

sex_code PC / Mobile string2

고객의 성별 코드입니다.
01 : 남성
02 : 여성ex) "sex_code" : "01"

local_code PC / Mobile string2

고객의 내국인·외국인 구분 코드입니다.
01 : 내국인
02 : 외국인ex) "local_code" : "01"

CI PC / Mobile string가변

CI는 연계정보 값입니다. 다른 웹사이트와의 제휴 서비스에서 동일 고객을 식별할 때 사용합니다.※ 해당 값은 웹 화면에 노출되지 않도록 처리해야 합니다.ex) "CI" : "fd3/2Qs0rBaz...dsdaffdsd=="

DI PC / Mobile string가변

DI는 중복가입 확인 값입니다. 동일 웹사이트 내에서 중복 가입 여부를 확인하거나 내부 회원을 관리할 때 사용합니다.※ 해당 값은 웹 화면에 노출되지 않도록 처리해야 합니다.ex) "DI" : "MC0DCSqGS...sdsQmQ5!K="

CI_URL PC / Mobile string가변

URL 인코딩된 CI 데이터입니다. CI 값에 특수문자가 포함될 수 있어, 값 누락을 방지하기 위해 URL 인코딩된 형태로 응답됩니다.
사용 시 URL 디코딩 후 CI 값으로 처리합니다.※ 해당 값은 웹 화면에 노출되지 않도록 처리해야 합니다.ex) "CI_URL" : "fd3/2Qs0rBa... 2dsdaffdsd=="

DI_URL PC / Mobile string가변

URL 인코딩된 DI 데이터입니다. 사용 시 URL 디코딩 후 DI 값으로 처리합니다.※ 해당 값은 웹 화면에 노출되지 않도록 처리해야 합니다.ex) "DI_URL" : "MC0DCSqGSivd3...sQmQ5!K="

per_cert_no PC / Mobile string40

본인확인 고유 인증 거래번호입니다.ex) "per_cert_no" : "25284339349648"

APP 연동 시 확인사항

모바일 앱 환경에서 본인확인 서비스를 연동하는 경우, PASS 앱 호출과 가맹점 앱 복귀가 정상적으로 동작하도록 안드로이드 패키지명을 설정해야 합니다. iOS는 Universal Link를 사용하므로 별도의 앱 스키마 설정이 필요하지 않습니다.

안드로이드 앱의 Intent 처리 방식은 앱 구조에 따라 다를 수 있으므로, 안드로이드 앱 개발 가이드를 참고하여 구현하세요.

PASS 앱, AOS 앱 패키지명 등록

※ targetSdkVersion 30(Android 11) 이상을 사용하는 경우, AndroidManifest.xml에 아래 패키지명을 선언해야 합니다.
패키지명이 선언되어 있지 않으면 PASS 앱 호출이 정상적으로 동작하지 않을 수 있으므로 확인하세요.

통신사	패키지명
SKT	com.sktelecom.tauth
KT	com.kt.ktauth
LGU+	com.lguplus.smartotp