자동결제 배치키 발급 API

해당 페이지는 NHN KCP 자동결제 배치키 발급 요청 및 응답에 대해 설명합니다.
배치키 발급은 최초 1회 고객 인증 후 자동결제 승인에 사용할 batch_key를 발급받는 단계입니다.
배치키 발급을 위한 결제창 인증이 정상 처리되면 인증 데이터(enc_data, enc_info)와 요청 코드(tran_cd)를 응답받습니다.
응답받은 인증 데이터를 변경하지 않고 배치키 발급 API로 전달하세요.

배치키 발급

배치키 결제 승인

요약

HTTP Method

POST 방식으로 JSON Body를 전송합니다.

Content-Type

application/json; charset=utf-8 형식으로 요청합니다.

통신 보안

TLS 1.2 이상 환경에서 통신합니다.

배치키 발급 테스트 URL

https://stg-spl.kcp.co.kr/gw/enc/v1/payment

배치키 발급 운영 URL

https://spl.kcp.co.kr/gw/enc/v1/payment

정상 응답 기준

res_cd 값이 0000이면 정상 처리입니다.

요청 정보

Request Body 예시

{
	"site_cd": "A52Q7",
	"kcp_cert_info": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
	"enc_data": "4m2DVGtmufY...Af6LdYF__",
	"enc_info": "3YSUGuuiWnhSnqdF...jXQ4Jv1f",
	"tran_cd": "00300001"
}

요청 파라미터

site_cd필수string5

길이 5자리로 영문대문자 또는 영문대문자+숫자로 구성됩니다. 모든 서비스에 사용합니다.ex) site_cd: A52Q7

kcp_cert_info필수string가변

NHN KCP에서 발급하는 서비스 인증서입니다.
파트너관리자 인증센터에서 다운로드한 PEM 파일 내용을 직렬화하여 사용합니다.ex) kcp_cert_info: -----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----

enc_data필수string가변

배치키 발급 결제창 인증 결과 암호화 정보입니다.
임의로 변경할 수 없으며 결제창에서 내려 주는 값을 그대로 사용합니다.ex) enc_data: 4m2DVGtmufY...Af6LdYF__

enc_info필수string가변

배치키 발급 결제창 인증 결과 암호화 정보입니다.
임의로 변경할 수 없으며 결제창에서 내려 주는 값을 그대로 사용합니다.ex) enc_info: 3YSUGuuiWnhSnqdF...jXQ4Jv1f

tran_cd필수string8

배치키 발급 결제창 인증 결과로 응답받은 요청 코드입니다. 배치키 발급 요청 시 응답받은 값을 그대로 전송합니다. 임의로 변경할 수 없습니다.ex) tran_cd: 00300001

응답 정보

배치키 발급이 정상 처리되면 배치키 승인 요청에 사용할 batch_key가 리턴됩니다. res_cd 값이 0000이 아니면 실패로 처리하세요.

Response Body 예시

{
	"res_cd": "0000",
	"res_msg": "정상처리",
	"batch_key": "21123011327740F3",
	"card_cd": "CCLG",
	"card_name": "신한카드",
	"card_bin_type_01": "0",
	"card_bin_type_02": "1"
}

응답 파라미터

res_cdstring4

결과 코드입니다. 정상 처리된 경우 0000을 리턴합니다.ex) res_cd: 0000

res_msgstring100

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

batch_keystring16

배치키입니다. 배치키 결제 요청에 사용하므로 가맹점 서버에서 안전하게 저장합니다.ex) batch_key: 21123011327740F3

card_cdstring4

배치키 발급 시 사용한 카드사 코드입니다.ex) card_cd: CCLG

card_namestring20

배치키 발급 시 사용한 카드사명입니다.ex) card_name: 신한카드

card_bin_type_01string1

카드빈 타입입니다. 0은 개인, 1은 법인입니다.
Mobile 환경에서만 응답됩니다.ex) card_bin_type_01: 0

card_bin_type_02string1

카드빈 타입입니다. 0은 신용, 1은 체크입니다.
Mobile 환경에서만 응답됩니다.ex) card_bin_type_02: 1

구현 참고사항

결제창 인증 결과를 변경하지 않고 배치키 발급 API로 전달합니다.

PHP 샘플 구현 포인트 보기

정상 처리 시 응답받은 batch_key는 다음 단계인 배치키 승인 API에서 사용하므로 가맹점 서버에 안전하게 저장하세요.

// 배치키 발급 API URL
$target_URL = "https://stg-spl.kcp.co.kr/gw/enc/v1/payment";

// 결제창 인증 완료 후 전달받은 값을 그대로 사용
$req_data = array(
  "site_cd"       => $site_cd,
  "kcp_cert_info" => $kcp_cert_info,
  "enc_data"      => $_POST["enc_data"],
  "enc_info"      => $_POST["enc_info"],
  "tran_cd"       => $_POST["tran_cd"]
);

// 정상 응답이면 res_cd 값이 0000
// 응답받은 batch_key는 배치키 승인 API에 사용하므로 서버에 저장
if ($res_data["res_cd"] == "0000") {
  $batch_key = $res_data["batch_key"];
}