자동결제
자동결제 서비스 연동하기
NHN KCP 자동결제 서비스는 신용, 체크카드만 지원합니다.
사용자의 카드 정보로 배치키를 발급 받고, 배치키로 결제 주기에 따라 결제 요청하는 서비스입니다.
일회성 결제는 결제할 때마다 고객의 인증이 필요합니다.
자동결제는 처음 배치키 발급에서만 고객 인증이 진행되고, 이후에는 인증 절차 없이 가맹점의 요청에 따라 결제가 진행됩니다.
주로 정기 배송, 정기 구독 등의 서비스에 사용되며 리스크 검토 및 별도 계약이 필요한 서비스입니다.
배치키란?
배치키는 고객의 카드번호, 유효기간 등 결제 정보를 암호화한 값입니다.
악용을 방지하기 위해 반드시 본인인증을 받은 뒤 배치키를 발급받는 것을 권장합니다.
자동결제 특징
배치키 기반 결제
최초 인증으로 카드 정보를 암호화한 배치키를 발급받고, 이후 결제 요청에 사용합니다.
반복 결제 지원
정기 구독, 정기 배송처럼 결제 주기가 있는 서비스에 적합합니다.
최초 인증 후 승인
배치키 발급 시 고객 인증을 진행하고, 이후 승인 요청은 가맹점 서버에서 처리합니다.
별도 계약 필요
자동결제는 리스크 검토 및 별도 계약이 필요한 서비스입니다.
자동결제 서비스 과정
1. Mobile 거래등록 하기
Mobile 환경에서는 결제창 호출 전, 주문·결제 정보를 미리 NHN KCP 결제 서버에 등록하는 거래등록이 필요합니다.
거래등록 응답으로 받은 approval_key·PayUrl을 결제창 호출 시 사용합니다.
2. 결제창 호출하기
거래등록 후, 결제창을 호출하여 본인확인 및 카드정보 수집을 진행합니다.
테스트 환경에서는 PASS 앱 인증 시 인증완료 버튼을 클릭하고, SMS 인증 시 임의의 숫자 6자리를 입력하세요.


Mobile 결제창 호출
Mobile 환경에서는 거래등록 후 call_pay_form 함수를 호출합니다.
거래등록 응답에서 리턴된 PayUrl(결제창 호출 주소)에 order_info를 전달해 결제창을 호출합니다.
function call_pay_form() { var v_frm = document.order_info; v_frm.action = v_frm.PayUrl.value; v_frm.submit(); }
<form name="order_info" method="post" action="PayUrl">
{
"site_cd":"A52Q7",
"pay_method":"AUTH",
"ActionResult":"batch",
"currency":"410",
"shop_name":"NHN KCP SHOP",
"Ret_URL":"https://your-shop.example.com/return",
"approval_key":"J9z6rqeRrRIjGoxmPPQtpgcHyKIPdQiE35VBPEo1sQ=",
"PayUrl":"https://testsmpay.kcp.co.kr/pay/mobileGW.kcp",
"ordr_idxx":"TEST123456789",
"kcp_group_id":"A52Q71000489",
"kcp_bath_info_view":"Y",
"good_name":"운동화",
"good_mny":"1000"
} PC 결제창 호출
PC 환경에서는 결제창 스크립트를 로드한 뒤 jsf_pay 함수에서 KCP_Pay_Execute_Web 메서드에 order_info를 전달합니다.
테스트 환경 : https://testspay.kcp.co.kr/plugin/kcp_spay_hub.js
운영 환경 : https://spay.kcp.co.kr/plugin/kcp_spay_hub.js
function jsf_pay(form) { try { KCP_Pay_Execute_Web(form); // 결제창 호출 } catch (e) { /* 브라우저에서 결제창 정상 종료 시 throw되는 스크립트 종료 예외 */ } }
<form name="order_info" method="post" action="배치키발급요청URL">
{
"site_cd":"A52Q7",
"site_name":"NHN KCP",
"pay_method":"AUTH:CARD",
"ordr_idxx":"TEST123456789",
"buyr_name":"홍길동",
"kcpgroup_id":"A52Q71000489",
"card_cert_type":"BATCH",
"module_type":"01",
"batch_soc":"Y",
"good_expr":"2:1m",
"good_name":"운동화",
"good_mny":"1000"
}결제창 호출 파라미터
※ 거래등록 시 전송한 Ret_URL 값과 동일한 값을 결제창 호출 form에도 함께 전송해야 합니다.
※ 콜백 응답 Body는 EUC-KR로 인코딩되어 전달되므로, 가맹점 서버에서 디코딩 처리가 필요합니다.ex) "Ret_URL" : "https://your-shop.example.com/return"
※ 자동결제 그룹 아이디 생성 방법
NHN KCP 가맹점관리자 → 결제 관리 → 자동결제 → 그룹관리를 통해 그룹 아이디를 생성합니다.
※ 자동결제 그룹 아이디 생성 방법
NHN KCP 가맹점관리자 → 결제 관리 → 자동결제 → 그룹관리를 통해 그룹 아이디를 생성합니다.
CK01 : 신용카드(Credit Card)
CK02 : 체크카드(Debit Card)
CK03 : 구매카드(Pre-paid Card)
CK04 : 기프트카드(Gift Card)ex) "kcp_restricted_card" : "CK02"
S : 주민번호만 표기
C : 사업자번호만 표기ex) "batch_soc_choice" : "S"
Y : 123412******1234 형식
L : 1234ex) "batch_cardno_return_yn" : "Y"
3. 결제창 인증 결과
결제창에서 인증이 완료되면 인증 결과 데이터가 가맹점으로 전달됩니다.
Mobile 환경에서는 거래등록 시 지정한 Ret_URL로 인증 결과 데이터가 리턴되고, PC 환경에서는 m_Completepayment 콜백 함수를 통해 인증 결과가 전달됩니다.
인증 결과의 res_cd 값이 0000이면 인증 성공이며, 이때 받은 enc_data·enc_info로 배치키 발급 및 결제 승인을 요청합니다.
결제창 인증 주요 파라미터
{
"res_cd":"0000",
"res_msg":"정상처리",
"tran_cd":"00100000",
"enc_data":"SnvXdGftIEjAequorkpNhJXc4u3GRuotLHW9vyDDOhdeorM4DPXMJgJllEoRo6divo=",
"enc_info":"3dsgjljlsSEGHsdccndsgnfdSDDhhbdrhffRbdfRYHFgfgnb=_"
} 결제창 인증 결과 파라미터
※ 임의로 변경할 수 없으며 결제창에서 내려 주는 값을 그대로 사용합니다.ex) "enc_data" : "SnvXdGftIEjAequorkpNhJXc4u3GRuotLHW9vyDDOhdeorM4DPXMJgJllEoRo6divo="
※ 임의로 변경할 수 없으며 결제창에서 내려 주는 값을 그대로 사용합니다.ex) "enc_info" : "3dsgjljlsSEGHsdccndsgnfdSDDhhbdrhffRbdfRYHFgfgnb=_"
4. 배치키 발급 요청하기
전달받은 인증 결과 데이터(enc_data·enc_info)를 API 통신으로 배치키 발급을 요청하는 단계입니다.
5. 배치키로 승인 요청하기
주문 정보와 발급받은 배치키를 사용해 결제 주기에 맞춰 자동결제 승인 요청합니다.
bt_group_id는 배치키 발급 단계에서 사용한 그룹아이디와 동일한 값을 사용하세요.