Guide > 자동결제
자동결제
자동결제
자동결제 서비스 연동하기
NHN KCP 자동결제 서비스는 신용, 체크카드만 지원합니다.
사용자의 카드 정보로 빌링키(배치키)를 발급 받고, 빌링키(배치키)로 결제 주기에 따라 결제 요청하는 서비스입니다.
일회성 결제는 매 시도에서 고객의 인증이 필요하지만, 자동결제는 처음 빌링키(배치키) 발급에서만 고객 인증이 진행되고, 이후에는 인증 절차 없이
가맹점의 요청에 따라 결제가 진행돼요. 정기 배송, 정기 구독 등의 서비스에 사용되며 리스크 검토 및 별도 계약이 필요한 서비스입니다.
🔑 빌링키(배치키)란?
빌링키(배치키)는 고객의 카드번호, 유효기간 등 결제 정보를 암호화한 값입니다.
악용되지 않도록 반드시 본인인증을 받은 뒤에 빌링키(배치키)를 발급받는 것을 권장드려요.
✅ 배치키 발급과 배치키로 결제 승인에 대한 과정은 API Reference를 확인해 주세요.
자동결제 서비스 과정
1. 서비스 인증서 적용하기
서비스 인증서는 가맹점 인증과 부인 방지를 위해 API 결제 서비스에서 사용돼요.
NHN KCP는 가맹점이 전달한 서비스 인증서 정보를 검증하고, 해당 결제 요청에 대한 결과를 응답합니다.
✅ 서비스 인증서에 대한 자세한 내용은 API Reference의 KCP PG-API를 확인해 주세요.
2. Mobile 거래등록 하기
모바일 버전에서는 결제 요청할 데이터 중 주문 및 결제 정보를 미리 NHN KCP 결제 서버에 등록하는 거래 등록이 필수입니다.
데이터 검증을 위해 결제 요청 전, 가맹점의 주문 요청 데이터를 서버에 저장해 주세요.
필수 주문 정보인 ordr_idxx, good_mny, pay_method, Ret_URL 파라미터의 값은 반드시 가맹점 서버에 저장하여 사용해 주세요.
🔗 거래등록 API Reference 바로가기
📍거래등록 API URL (target URL)
테스트 : https://testsmpay.kcp.co.kr/trade/register.do
운영 : https://smpay.kcp.co.kr/trade/register.do
//거래등록 필수 파라미터
"site_cd" : "T0000",
"ordr_idxx" : "TEST123456789",
"good_mny" : "1000",
"good_name" : "운동화",
"pay_method" : "AUTH",
"Ret_URL" : "https://쇼핑몰주문처리서버/../return"
3. 결제창 호출하기
거래등록 후, 결제창을 호출하여 본인확인 및 카드정보 수집을 진행합니다.
테스트 환경일 경우 PASS 앱 인증 시 [인증완료] 버튼 클릭, SMS 인증일 경우 [임의의 숫자 6자리] 기입해주세요.
Mobile 결제창 호출
모바일 환경의 경우, 거래등록 후 call_pay_form 함수를 호출합니다.
call_pay_form 함수를 호출하면, 거래등록 응답에서 리턴된 PayUrl(결제창 호출 주소)로 order_info을 전달하여 결제창을 띄웁니다.
✅ 거래 등록의 데이터와 order_info 데이터가 다를 경우 결제창에서 오류를 리턴합니다.
✅ PayUrl은 리턴된 그대로 사용해주세요.
function call_pay_form()
{
var v_frm = document.order_info;
var PayUrl= v_frm.PayUrl.value;
v_frm.action = PayUrl.substring(0,PayUrl.lastIndexOf("/")) + "/jsp/encodingFilter/encodingFilter.jsp";
v_frm.submit();
}
📍Mobile 결제창 호출 필수 파라미터
<form name="order_info" method="post" action="승인요청URL">
{
"site_cd":"T0000",
"pay_method":"AUTH",
"currency":"410",
"shop_name":"TEST SITE",
"Ret_URL":"https://쇼핑몰주문처리서버/../return",
"approval_key":"J9z6rqeRrRIjGoxmPPQtpgcHyKIPdQiE35VBPEo1sQ=",
"PayUrl":"https://testsmpay.kcp.co.kr/pay/mobileGW.kcp",
"ordr_idxx":"TEST123456789",
"good_name":"운동화",
"good_cd":"00",
"good_mny":"1000"
}
PC 결제창 호출
PC결제창의 경우,
KCP_Pay_Execute_Web 메서드에 order_info를 전달합니다.
PC결제창은 JS스크립트를 이용해 결제창을 띄웁니다.
<script type="text/javascript" src="https://testspay.kcp.co.kr/plugin/kcp_spay_hub.js"></script>
테스트 환경 : https://testspay.kcp.co.kr/plugin/kcp_spay_hub.js.
운영 환경 : https://spay.kcp.co.kr/plugin/kcp_spay_hub.js
PC결제창 호출 함수 : jsf__pay
KCP_Pay_Excute_Web 을 통해 결제창 호출.
function jsf__pay( form )
{
try
{
KCP_Pay_Execute_Web( form ); // 결제창 호출 메서드
}
catch (e)
{
/* 브라우저에서 결제 정상종료시 throw로 스크립트 종료 */
}
}
📍PC 결제창 호출 필수 파라미터
<form name="order_info" method="post" action="승인요청URL">
{
"site_cd":"T0000",
"site_name":"TEST SITE",
"pay_method":"AUTH:CARD",
"ordr_idxx":"TEST123456789",
"good_name":"운동화",
"good_cd":"00",
"good_mny":"1000"
}
결제창 호출 파라미터
site_cd필수PC / Mobile
길이 5자리로 영문대문자 또는 영문대문자+숫자로 구성됩니다.
모든 서비스에 사용합니다.
ex) "site_cd" : "A52Q7"
pay_method필수PC / Mobile
PC, MOBILE 결제수단 코드 값 입니다.
Mobile - "pay_method" : "AUTH"
PC - "pay_method" : "AUTH:CARD"
PayUrl필수Mobile
결제창 호출 주소.
거래등록에서 전달받은 그대로 사용해주세요
ex) TEST일 경우, "PayUrl" : "https://testsmpay.kcp.co.kr/pay/mobileGW.kcp"
approval_key필수Mobile
거래 인증 키
(거래등록 후 리턴받은 approvalKey 값을 셋팅해주세요. )
ex) "approval_key" : "ockLyC3QHxD5rSUio3ETuAcHyKIPdQiE35VBPEo1cQ="
Ret_URL필수Mobile
리다이렉트 URL
인증결과를 리턴받을 가맹점의 URL
ex) "Ret_URL" : "https://쇼핑몰주문처리서버/../return"
AppUrlMobile
외부 앱에서 가맹점 앱으로 돌아오기 위해 사용하는 URL
앱 연동시 필수이며, 가맹점 앱을 초기화 하는 주소가 아닌 결제창을 호출한 웹뷰가 유지되는 주소를 사용해주세요.
https 값이 아닌 '앱스킴명://' 형식으로 입력합니다.
ex) "AppUrl" : "myapp://"
ordr_idxx필수PC / Mobile
상점에서 관리하는 주문번호입니다. 중복되지 않는 유니크한 값으로 사용하시길 권장합니다.
주문 데이터 관리를 위해 가맹점에서 반드시 저장해야합니다.
ex) "ordr_idxx" : "TEST123456789"
good_mny필수PC / Mobile
결제 금액입니다.
ex) "good_mny" : "1000"
good_name필수PC / Mobile
상품명입니다. 최대길이는 100자입니다.
ex) "good_name" : "운동화"
currency필수PC / Mobile
화폐단위
※ Mobile 원화 - 410
※ PC 원화 - WON
ex) 모바일의 경우, "currency" : "410"
ActionResultMobile
인증방식(영문소문자)으로 배치키 발급의 경우 batch(고정)입니다.
ex) "ActionResult" : "batch"
shop_nameMobile
사이트명
ex) "shop_name" : "NHN KCP SHOP"
site_namePC
상점이름(영문으로 작성권장)
ex) "site_name" = "NHN KCP"
buyr_namePC / Mobile
주문자이름
ex) "buyr_name" : "홍길동"
kcp_group_id필수Mobile
자동결제 그룹 아이디이며, 배치키 발급 및 승인 시 그룹별로 관리할 수 있습니다.
ex) "kcp_group_id" : "A52Q71000489"
※ 자동결제 그룹 아이디 생성 방법
NHN KCP 상점관리자 → 결제 관리 → 자동결제 → 그룹관리를 통해 그룹 아이디 생성
kcpgroup_id필수PC
자동결제 그룹 아이디이며, 배치키 발급 및 승인 시 그룹별로 관리할 수 있습니다.
ex) "kcpgroup_id" : "A52Q71000489"
※ 자동결제 그룹 아이디 생성 방법
NHN KCP 상점관리자 → 결제 관리 → 자동결제 → 그룹관리를 통해 그룹 아이디 생성
card_cert_typePC
인증방식으로 배치키 발급의 경우 BATCH(고정)입니다.
ex) "card_cert_type" : "BATCH"
module_typePC
결제창 설정 정보입니다. 01 의 고정값을 사용합니다.
ex) "module_type" : "01"
batch_socPC
NHN KCP 결제창 내에서 생년월일 사용값으로, Y로 고정값 입니다.
ex) "batch_so" : "Y"
good_exprPC
NHN KCP 결제창에 노출되는 제공기간 설정 변수입니다.
해당 값을 설정하지 않는 경우, 결제창에서 [자동결제]로 노출됩니다.
ex) "good_expr" : "2:1m" -> [1개월 자동결제]로 표기
batch_soc_choicePC / Mobile
NHN KCP 결제창에서 주민번호/사업자번호를 설정합니다.
S : 주민번호만 표기
C: 사업자번호만 표기
ex) "batch_soc_choice" : "S"
batch_cardno_return_ynPC / Mobile
배치키 발급 시 사용한 카드의 카드번호의 리턴여부를 설정합니다.
Y : 123412******1234 형식
L : 1234
ex) "batch_cardno_return_yn" : "Y"
param_opt_1 Mobile
NHN KCP 기본 파라미터 외 업체 추가 파라미터입니다.
ex) "param_opt_1" : "test"
param_opt_2 Mobile
NHN KCP 기본 파라미터 외 업체 추가 파라미터입니다.
ex) "param_opt_2" : "test"
param_opt_3 Mobile
NHN KCP 기본 파라미터 외 업체 추가 파라미터입니다.
ex) "param_opt_3" : "test"
4. 결제창 인증 결과
결제창에서 인증을 진행한 후 인증에 대한 결과를 응답받습니다.
응답 파라미터 중 enc_info, enc_data 는 인증 정보를 암호화한 값으로, 리턴된 그대로 결제 요청해 주세요.
✅ 빌링키(배치키) 발급과 결제 승인은 API Reference를 확인해 주세요.
결제창 인증 주요 파라미터
{
"res_cd":"0000",
"res_msg":"정상처리",
"tran_cd":"00100000",
"enc_data":"SnvXdGftIEjAequorkpNhJXc4u3GRuotLHW9vyDDOhdeorM4DPXMJgJlIEoRo6divo=",
"enc_info":"3dsgjljlsSEGHsdccndsgnfdSDDhhbdrhffRbdfRYHFgfgnb=_"
}
Mobile 결제창 인증 결과
결제창 인증이 완료되면 Ret_URL로 거래 등록에서 넘긴 파라미터에 대한 결과가 리턴됩니다.
리턴된 데이터는 form 형식의 pay_form으로 전달되며,
PayUrl로 보낸 결제 요청 데이터와 Ret_URL로 돌아온 데이터가 동일한지 확인해 보세요.
PC 결제창 인증 결과
PC 버전은 m_Completepayment 콜백 함수를 통해 enc_info, enc_data 가 리턴됩니다.
결제창 인증 결과 파라미터
res_cdPC / Mobile
결과코드
인증 정상인 경우 '0000'값 리턴
ex) "res_cd" : "0000"
res_msgPC / Mobile
결과메세지
ex) "res_msg" : "정상처리"
site_cdMobile
길이 5자리로 영문대문자 또는 영문대문자+숫자로 구성됩니다.
모든 서비스에 사용합니다.
ex) "site_cd" : "T0000"
enc_dataPC / Mobile
결제창 인증결과 암호화 정보
통합 결제 창으로부터 전달 받는 인증결과 암호화 데이터
※ 절대 임의로 변경 불가하며 결제 창에서 내려 주는 값을 그대로 사용 부탁 드립니다.
ex) "enc_data" : "1eOSNbDDMQCVqCHVNZGNPKZErG2lCPBL24RTDIATPEXWERwBkrN4ghC4M0ue81I8y-LZ1tl6q8CMpw-LvpFdQDKzbHx5tx1OYWBf"
enc_infoPC / Mobile
결제창 인증결과 암호화 정보
통합 결제 창으로부터 전달 받는 인증결과 암호화 데이터
※ 절대 임의로 변경 불가하며 결제 창에서 내려 주는 값을 그대로 사용 부탁 드립니다.
ex) "enc_info” : "4dgxMICIupJdwMheYKVQI.Vd6cKDpBSSkWfEfW1k431UaMlGzuVl1N.NIsrbdDnQ5i9Mu.JVz.C7JIK1NpdfDkdYd"
tran_cdPC / Mobile
요청코드(수정불가)
ex) "tran_cd" : "00100000"