자동결제 배치키 결제 승인 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-----
파트너관리자 인증센터에서 다운로드한 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
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"); // 주문번호, 거래번호, 승인 금액을 가맹점 서버에 저장 }