본인확인 거래등록 API
해당 페이지는 NHN KCP 본인확인 V2의 거래등록 요청 및 응답에 대해 설명합니다.
본인확인 거래등록은 인증 절차를 시작하기 전에 인증 요청 정보를 NHN KCP에 등록하여, 본인확인 인증창 호출 및 결과 조회에 필요한 정보를 발급받는 API입니다.
가맹점에서 생성한 JSON 데이터를 NHN KCP에서 제공하는 라이브러리의 encryptJson 함수를 이용하여 enc_data와 rv를 생성하고, enc_data는 Request Body로, site_cd와 rv는 Header로 전송합니다.
정상 응답으로 받은 reg_cert_key는 안전하게 저장하고, call_url은 변경하지 않은 채 본인확인 인증창 호출에 사용하세요.
요약
대상 서비스
본인확인 V2
HTTP Method
POST 방식으로 요청합니다.
Content-Type
application/json; charset=utf-8 형식으로 요청합니다.
통신 보안
TLS 1.2 이상 환경에서 통신합니다.
테스트 URL
https://testcert.kcp.co.kr/api/reg/certDataReg.do
운영 URL
https://cert.kcp.co.kr/api/reg/certDataReg.do
Request Body
encryptJson 함수로 생성한 enc_data 문자열을 직접 전송합니다.
정상 응답 기준
res_cd 값이 0000이면 정상 처리입니다.
요청 정보
Request Header 예시
Content-Type: application/json site_cd: AO7F3 rv: Q2hhbmd1VGh...HQ=
Header 파라미터
본인확인 거래등록과 결과 조회에는 동일한 사이트코드를 사용합니다.ex) site_cd: AO7F3
암호화 라이브러리의 encryptJson 함수에서 enc_data와 함께 생성된 값을 그대로 전송합니다. 본인확인 거래등록에서만 사용하며 결과 조회 요청에는 포함하지 않습니다.ex) rv: Q2hhbmd1VGh...HQ=
암호화 전 요청 JSON 예시
{
"site_cd": "AO7F3",
"ordr_idxx": "TEST1234567890",
"Ret_URL": "https://example.com/kcp/return",
"web_siteid": "J12345678901"
} Request Body 예시
암호화 전 JSON을 encryptJson 함수로 처리한 뒤 생성된 enc_data 문자열만 Body에 직접 전송합니다.
nLyG/5nbyqYuUw9f...6d1SkGI/DzIKksQ6xiTs 요청 파라미터
Header의 site_cd와 동일한 값을 입력합니다.ex) site_cd: AO7F3
본인확인 서비스는 파트너관리자에 해당 Ret_URL 도메인을 반드시 등록해야 합니다.ex) Ret_URL: https://example.com/kcp/return
응답 정보
거래등록 실패 시 res_cd, res_msg 외의 응답 데이터는 리턴되지 않습니다.
call_url은 변경될 수 있으므로 반드시 거래등록 응답으로 받은 값을 사용하고, reg_cert_key는 외부에 노출되지 않도록 관리하세요.
Response Body 예시
{
"res_cd": "0000",
"res_msg": "정상처리",
"call_url": "https://testcert.kcp.co.kr/cert/...",
"reg_cert_key": "1234567890123456"
} 응답 파라미터
구현 참고사항
첨부한 JSP 샘플의 암호화 처리, Header 설정, 거래등록 API 호출 및 응답 데이터 저장 방식을 기준으로 작성했습니다.
JSP 샘플 구현 포인트 보기
샘플은 암호화 전 JSON을 생성한 후 Crypto.encryptJson()으로 enc_data와 rv를 생성합니다. enc_data는 Body에 직접 기록하고, site_cd와 rv는 Header에 설정합니다.
// 암호화 전 요청 JSON 구성 JSONObject req_data = new JSONObject(); req_data.put("site_cd", "AO7F3"); req_data.put("ordr_idxx", "TEST1234567890"); req_data.put("Ret_URL", "https://example.com/kcp/return"); req_data.put("web_siteid", "J12345678901"); req_data.put("param_opt_1", ""); req_data.put("param_opt_2", ""); req_data.put("param_opt_3", ""); Map<String, String> encResult = Crypto.encryptJson(req_data.toJSONString(), enc_key, "AO7F3"); String enc_data = encResult.get("encData"); String rv = encResult.get("rv");
// 본인확인 거래등록 API 호출 URL url = new URL("https://testcert.kcp.co.kr/api/reg/certDataReg.do"); HttpURLConnection conn = (HttpURLConnection) url.openConnection(); conn.setDoOutput(true); conn.setRequestMethod("POST"); conn.setRequestProperty("Content-Type", "application/json"); conn.setRequestProperty("site_cd", "AO7F3"); conn.setRequestProperty("rv", rv); try (OutputStream os = conn.getOutputStream()) { os.write(enc_data.getBytes(StandardCharsets.UTF_8)); os.flush(); } JSONObject reg_result = (JSONObject) new JSONParser().parse(responseBody); String res_cd = (String) reg_result.get("res_cd"); String call_url = (String) reg_result.get("call_url"); String reg_cert_key = (String) reg_result.get("reg_cert_key"); if ("0000".equals(res_cd)) { // call_url은 인증창 호출에 사용 // reg_cert_key와 ordr_idxx는 결과 조회 전까지 DB에 안전하게 저장 }
제공 샘플은 이해를 돕기 위해 세션에 reg_cert_key와 ordr_idxx를 저장하지만, 운영 환경에서는 DB 또는 별도 보안 저장소를 사용하는 것이 안전합니다. ENC_KEY와 site_cd도 외부에 노출하거나 클라이언트 코드에 포함하지 마세요.