전담지원 신청
API Reference > 자동결제 > 배치키 결제 승인

자동결제 배치키 결제 승인 API

해당 페이지는 NHN KCP 자동결제 배치키 결제 승인 요청 및 응답에 대해 설명합니다.
배치키 결제 승인은 배치키 발급 API에서 받은 batch_key와 주문·결제 정보를 사용해 결제창 없이 자동결제를 승인하는 단계입니다.
요청 시 bt_batch_key에는 발급받은 batch_key를 입력하고, bt_group_id에는 배치키 발급 단계에서 사용한 그룹아이디와 동일한 값을 입력하세요.

배치키 발급
배치키 결제 승인

요약

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-----...-----END CERTIFICATE-----",
	"pay_method": "CARD",
	"media_type": "MC01",
	"amount": "1000",
	"card_mny": "1000",
	"currency": "410",
	"quota": "00",
	"ordr_idxx": "TEST123456789",
	"good_name": "정기 구독 상품",
	"buyr_name": "홍길동",
	"buyr_mail": "test@your-shop.example.com",
	"buyr_tel2": "010-1234-1234",
	"card_tx_type": "11511000",
	"bt_batch_key": "21123011327740F3",
	"bt_group_id": "A52Q71000489"
}

요청 파라미터

site_cd필수string5
길이 5자리로 영문대문자 또는 영문대문자+숫자로 구성됩니다. 모든 서비스에 사용합니다.ex) site_cd: A52Q7
kcp_cert_info필수string가변
NHN KCP에서 발급하는 서비스 인증서입니다.
파트너관리자 인증센터에서 다운로드한 PEM 파일 내용을 직렬화하여 사용합니다.ex) kcp_cert_info: -----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----
pay_method필수string4
자동결제 승인 결제수단 코드입니다. CARD 고정값을 사용합니다.ex) pay_method: CARD
media_type필수string4
매체 구분입니다.
PC는 MC01, Mobile은 MC02를 사용합니다.ex) media_type: MC01
amount필수number12
총 결제 금액입니다. 콤마·소수점 없이 숫자만 입력합니다.ex) amount: 1000
card_mny필수number12
카드로 결제할 금액입니다. 콤마·소수점 없이 숫자만 입력합니다.ex) card_mny: 1000
currency필수string3
거래 화폐 단위입니다. 원화(KRW)는 410을 사용합니다.ex) currency: 410
quota필수string2
할부 개월 수입니다. 자동결제 승인에서는 00 고정값을 사용합니다.ex) quota: 00
ordr_idxx필수string50
가맹점에서 관리하는 주문번호입니다. 중복되지 않는 유니크한 값으로 사용하고, 가맹점에서 반드시 저장합니다.ex) ordr_idxx: TEST123456789
good_name필수string100
상품명입니다.ex) good_name: 정기 구독 상품
buyr_namestring40
주문자 이름입니다.ex) buyr_name: 홍길동
buyr_mailstring100
주문자 이메일입니다. 결제 결과 메일 발송 등에 사용됩니다.ex) buyr_mail: test@your-shop.example.com
buyr_tel2string20
주문자 휴대폰 번호입니다. 하이픈(-)을 포함할 수 있습니다.ex) buyr_tel2: 010-1234-1234
card_tx_type필수string8
카드 전문 유형입니다. 자동결제 승인에서는 11511000 고정값을 사용합니다.ex) card_tx_type: 11511000
bt_batch_key필수string16
자동결제 배치키 발급 API의 응답으로 받은 batch_key입니다. 클라이언트에 노출하지 않고 가맹점 서버에 안전하게 저장한 값을 사용합니다.ex) bt_batch_key: 21123011327740F3
bt_group_id필수string12
자동결제 그룹 아이디입니다. 배치키 발급 단계에서 사용한 그룹아이디와 동일한 값을 사용합니다.ex) bt_group_id: A52Q71000489

응답 정보

Response Body 예시

{
	"res_cd": "0000",
	"res_msg": "정상처리",
	"res_en_msg": "processing completed",
	"pay_method": "PACA",
	"tno": "21599969123456",
	"order_no": "TEST123456789",
	"amount": "1000",
	"card_mny": "1000",
	"card_cd": "CCBC",
	"card_name": "비씨카드",
	"card_no": "123456******1234",
	"app_time": "20260101123045",
	"app_no": "12345678",
	"noinf": "N",
	"quota": "00",
	"partcanc_yn": "Y",
	"card_bin_type_01": "0",
	"card_bin_type_02": "0"
}

응답 파라미터

res_cdstring4
응답 코드입니다. 정상 처리 시 0000을 리턴합니다.ex) res_cd: 0000
res_msgstring100
결과 메시지입니다.ex) res_msg: 정상처리
res_en_msgstring100
영문 결과 메시지입니다.ex) res_en_msg: processing completed
pay_methodstring4
승인 결과 결제수단입니다. 카드 승인 시 PACA가 리턴됩니다.ex) pay_method: PACA
tnostring14
NHN KCP 거래번호입니다. 승인, 조회, 취소 등 후속 처리 시 사용하므로 반드시 저장합니다.ex) tno: 21599969123456
order_nostring50
가맹점 주문번호입니다. 요청의 ordr_idxx에 대응하는 값입니다.ex) order_no: TEST123456789
amountnumber12
승인 금액입니다.ex) amount: 1000
card_mnynumber12
카드로 승인된 금액입니다.ex) card_mny: 1000
card_cdstring4
결제 건의 카드사 코드입니다.ex) card_cd: CCBC
card_namestring20
결제 건의 카드사명입니다.ex) card_name: 비씨카드
card_nostring16
마스킹된 카드번호입니다.ex) card_no: 123456******1234
app_timestring14
카드 승인 일시입니다. yyyyMMddHHmmss 형식으로 리턴됩니다.ex) app_time: 20260101123045
app_nostring8
카드 승인번호입니다.ex) app_no: 12345678
noinfstring1
무이자 할부 적용 여부입니다.ex) noinf: N
quotastring2
승인된 할부 개월 수입니다. 일시불은 00입니다.ex) quota: 00
partcanc_ynstring1
부분취소 가능 여부입니다.ex) partcanc_yn: Y
trace_nostring16
NHN KCP 추적번호입니다.ex) trace_no: A52Q7C0000GL000Q
card_bin_type_01string1
카드빈 타입입니다. 0은 개인, 1은 법인입니다.ex) card_bin_type_01: 0
card_bin_type_02string1
카드빈 타입입니다. 0은 신용, 1은 체크입니다.ex) card_bin_type_02: 0

구현 참고사항

첨부한 PC·Mobile JSP 샘플의 요청 전문 구성과 HTTPS 호출 방식을 기준으로 작성했습니다.

JSP 샘플 구현 포인트 보기

첨부 JSP 샘플은 화면 입력값 good_mny를 승인 전문의 amount와 card_mny에 매핑하고, JSONObject와 HttpURLConnection으로 승인 API를 호출합니다. 아래 예시는 페이지 규격에 맞춰 cust_ip를 제외하고 media_type을 추가했습니다.

// 자동결제 배치키 승인 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 ordr_idxx    = f_get_parm(request.getParameter("ordr_idxx"));
String good_name    = f_get_parm(request.getParameter("good_name"));
String good_mny     = f_get_parm(request.getParameter("good_mny"));
String buyr_name    = f_get_parm(request.getParameter("buyr_name"));
String buyr_mail    = f_get_parm(request.getParameter("buyr_mail"));
String buyr_tel2    = f_get_parm(request.getParameter("buyr_tel2"));
String bt_batch_key = f_get_parm(request.getParameter("bt_batch_key"));
String bt_group_id  = f_get_parm(request.getParameter("bt_group_id"));
String media_type   = f_get_parm(request.getParameter("media_type"));
// PC: MC01, Mobile: MC02

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", "CARD");
json_req.put("media_type", media_type);
json_req.put("amount", good_mny);
json_req.put("card_mny", good_mny);
json_req.put("currency", "410");
json_req.put("quota", "00");
json_req.put("ordr_idxx", ordr_idxx);
json_req.put("good_name", good_name);
json_req.put("buyr_name", buyr_name);
json_req.put("buyr_mail", buyr_mail);
json_req.put("buyr_tel2", buyr_tel2);
json_req.put("card_tx_type", "11511000");
json_req.put("bt_batch_key", bt_batch_key);
json_req.put("bt_group_id", bt_group_id);

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

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();

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

// 정상 승인 처리
if ("0000".equals(res_cd)) {
  String tno = (String) json_res.get("tno");
  // 주문번호, 거래번호, 승인 금액을 가맹점 서버에 저장
}