자동결제 배치키 폐기 API

해당 페이지는 NHN KCP 자동결제 배치키 폐기 요청 및 응답에 대해 설명합니다.
정기 구독 해지 등으로 더 이상 배치키를 사용하지 않을 때, 배치키 발급 단계에서 받은 batch_key와 그룹아이디를 사용해 폐기를 요청합니다.
자동결제 해지 전에는 고객에게 해지 사실을 사전에 안내하고, 폐기 결과가 정상 처리된 경우 가맹점의 배치키 상태도 함께 갱신하세요.

배치키 발급

배치키 결제 승인

Option배치키 폐기

요약

HTTP Method

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

Content-Type

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

통신 보안

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

테스트 URL

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

운영 URL

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

정상 응답 기준

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

요청 정보

Request Body 예시

{
	"site_cd": "A52Q7",
	"kcp_cert_info": "-----BEGIN CERTIFICATE-----MIIDgTCCAm.....MOOpuQ==-----END CERTIFICATE-----",
	"pay_method": "BATCH",
	"tx_type": "10005010",
	"batch_key": "2112151156695850",
	"group_id": "A52Q71000489"
}

요청 파라미터

site_cd필수string5

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

kcp_cert_info필수string가변

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

pay_method필수string5

배치키 폐기 결제수단 코드입니다. BATCH 고정값을 사용합니다.ex) pay_method: BATCH

tx_type필수string8

배치키 폐기 요청 유형입니다. 10005010 고정값을 사용합니다.ex) tx_type: 10005010

batch_key필수string16

배치키입니다. 배치키 발급 API 응답으로 받은 값을 그대로 사용합니다.ex) batch_key: 2112151156695850

group_id필수string12

배치키 발급 시 사용한 가맹점 그룹아이디입니다. 발급 단계와 동일한 값을 입력합니다.ex) group_id: A52Q71000489

응답 정보

Response Body 예시

{
	"res_cd": "0000",
	"res_msg": "정상처리"
}

응답 파라미터

res_cdstring4

응답 코드입니다. 정상 처리 시 0000 을 리턴합니다.ex) res_cd: 0000

res_msgstring100

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

구현 참고사항

첨부한 PC·Mobile JSP 샘플의 요청 전문 구성과 HTTPS 호출 방식을 기준으로 작성했습니다. 두 샘플은 동일한 필드와 API URL을 사용합니다.

JSP 샘플 구현 포인트 보기

화면에서 입력받은 batch_key와 group_id를 서버로 전달하고, 서버에서 서비스 인증서와 고정값을 조합하여 폐기 API를 호출합니다. 서비스 인증서 전체 내용은 샘플처럼 소스에 직접 노출하기보다 안전한 서버 설정이나 비밀 저장소에서 불러오는 방식을 권장합니다.

// 자동결제 배치키 폐기 API URL
String target_URL = "https://stg-spl.kcp.co.kr/gw/hub/v1/payment";
// 운영: https://spl.kcp.co.kr/gw/hub/v1/payment

request.setCharacterEncoding("UTF-8");

String site_cd   = f_get_parm(request.getParameter("site_cd"));
String batch_key = f_get_parm(request.getParameter("batch_key"));
String group_id  = f_get_parm(request.getParameter("group_id"));

JSONObject json_req = new JSONObject();
json_req.put("site_cd", site_cd);
json_req.put("kcp_cert_info", kcp_cert_info);
json_req.put("pay_method", "BATCH");
json_req.put("tx_type", "10005010");
json_req.put("batch_key", batch_key);
json_req.put("group_id", group_id);

String req_data = json_req.toString();
StringBuilder outResult = new StringBuilder();

URL url = new URL(target_URL);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setDoOutput(true);
conn.setRequestMethod("POST");
conn.setRequestProperty("Content-Type", "application/json; charset=utf-8");
conn.setRequestProperty("Accept-Charset", "UTF-8");

try (OutputStream os = conn.getOutputStream()) {
  os.write(req_data.getBytes(StandardCharsets.UTF_8));
  os.flush();
}

try (BufferedReader in = new BufferedReader(
    new InputStreamReader(conn.getInputStream(), StandardCharsets.UTF_8))) {
  String inputLine;
  while ((inputLine = in.readLine()) != null) {
    outResult.append(inputLine);
  }
}
conn.disconnect();

JSONObject json_res = (JSONObject) new JSONParser().parse(outResult.toString());
String res_cd = (String) json_res.get("res_cd");
String res_msg = (String) json_res.get("res_msg");

// 정상 폐기 처리
if ("0000".equals(res_cd)) {
  // 가맹점 DB의 배치키 상태를 '폐기 완료'로 변경
} else {
  // 결과 코드와 메시지를 기록하고 실패 처리
}