전담지원 신청
Guide > 자동결제

자동결제

자동결제 서비스 연동하기

NHN KCP 자동결제 서비스는 신용, 체크카드만 지원합니다.
사용자의 카드 정보로 배치키를 발급 받고, 배치키로 결제 주기에 따라 결제 요청하는 서비스입니다.

일회성 결제는 결제할 때마다 고객의 인증이 필요합니다.
자동결제는 처음 배치키 발급에서만 고객 인증이 진행되고, 이후에는 인증 절차 없이 가맹점의 요청에 따라 결제가 진행됩니다.
주로 정기 배송, 정기 구독 등의 서비스에 사용되며 리스크 검토 및 별도 계약이 필요한 서비스입니다.

배치키란?

배치키는 고객의 카드번호, 유효기간 등 결제 정보를 암호화한 값입니다.
악용을 방지하기 위해 반드시 본인인증을 받은 뒤 배치키를 발급받는 것을 권장합니다.

자동결제 특징

배치키 기반 결제

최초 인증으로 카드 정보를 암호화한 배치키를 발급받고, 이후 결제 요청에 사용합니다.

반복 결제 지원

정기 구독, 정기 배송처럼 결제 주기가 있는 서비스에 적합합니다.

최초 인증 후 승인

배치키 발급 시 고객 인증을 진행하고, 이후 승인 요청은 가맹점 서버에서 처리합니다.

별도 계약 필요

자동결제는 리스크 검토 및 별도 계약이 필요한 서비스입니다.

자동결제 서비스 과정

1. Mobile 거래등록 하기

Mobile 환경에서는 결제창 호출 전, 주문·결제 정보를 미리 NHN KCP 결제 서버에 등록하는 거래등록이 필요합니다.
거래등록 응답으로 받은 approval_key·PayUrl을 결제창 호출 시 사용합니다.

거래등록 요청과 응답 파라미터는 API Reference > 거래등록을 확인하세요.

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();
}
Mobile 결제창 호출 폼 파라미터 (order_info)
<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되는 스크립트 종료 예외 */
	}
}
PC 결제창 호출 폼 파라미터 (order_info)
<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"
}

결제창 호출 파라미터

site_cd필수PC / Mobilestring5
NHN KCP가 발급한 사이트(가맹점) 코드입니다. 모든 서비스에 동일하게 사용됩니다.ex) "site_cd" : "A52Q7"
pay_method필수PC / Mobilestring49
자동결제 결제창 호출 시 사용하는 결제수단 코드 값입니다.ex) Mobile - "pay_method" : "AUTH"ex) PC - "pay_method" : "AUTH:CARD"
PayUrl필수Mobilestring가변
결제창 호출 주소입니다. 거래등록 응답으로 리턴된 PayUrl 값을 그대로 사용합니다.ex) "PayUrl" : "https://testsmpay.kcp.co.kr/pay/mobileGW.kcp"
approval_key필수Mobilestring가변
거래 인증 키입니다. 거래등록 응답으로 리턴된 approvalKey 값을 그대로 사용합니다.※ 거래등록 응답의 필드명은 approvalKey이지만, 결제창 호출 시 form 필드명은 반드시 approval_key로 변환하여 전송해야 합니다.ex) "approval_key" : "J9z6rqeRrRIjGoxmPPQtpgcHyKIPdQiE35VBPEo1sQ="
Ret_URL필수Mobilestring256
인증 완료 후 결과를 리턴받을 가맹점 응답 주소입니다. https로 시작하는 가맹점 도메인 주소를 입력합니다.
※ 거래등록 시 전송한 Ret_URL 값과 동일한 값을 결제창 호출 form에도 함께 전송해야 합니다.
※ 콜백 응답 Body는 EUC-KR로 인코딩되어 전달되므로, 가맹점 서버에서 디코딩 처리가 필요합니다.ex) "Ret_URL" : "https://your-shop.example.com/return"
ordr_idxx필수PC / Mobilestring50
가맹점에서 관리하는 주문번호입니다. 중복되지 않는 유니크한 값으로 사용하고, 가맹점에서 반드시 저장합니다.ex) "ordr_idxx" : "TEST123456789"
good_mny필수PC / Mobilenumber12
결제 금액입니다. 콤마·소수점 없이 숫자만 입력합니다.ex) "good_mny" : "1000"
good_name필수PC / Mobilestring100
상품명입니다.ex) "good_name" : "운동화"
currency필수Mobilestring3
결제 통화 코드입니다. 원화(KRW)는 410을 사용합니다.ex) "currency" : "410"
ActionResult필수Mobilestring5
배치키 발급을 위한 인증 방식입니다. Mobile 환경에서는 batch로 설정합니다.ex) "ActionResult" : "batch"
shop_nameMobilestring20
가맹점(사이트)명입니다. 결제창과 영수증에 노출됩니다.ex) "shop_name" : "NHN KCP SHOP"
site_namePCstring20
사이트명입니다.ex) "site_name" : "NHN KCP"
buyr_namePC 필수Mobile 선택string40
주문자 이름입니다.ex) "buyr_name" : "홍길동"
kcp_group_id필수Mobilestring12
자동결제 그룹 아이디입니다. 배치키 발급 및 승인 시 그룹별로 관리할 수 있습니다.ex) "kcp_group_id" : "A52Q71000489"
※ 자동결제 그룹 아이디 생성 방법
NHN KCP 가맹점관리자 → 결제 관리 → 자동결제 → 그룹관리를 통해 그룹 아이디를 생성합니다.
kcpgroup_id필수PCstring12
자동결제 그룹 아이디입니다. 배치키 발급 및 승인 시 그룹별로 관리할 수 있습니다.ex) "kcpgroup_id" : "A52Q71000489"
※ 자동결제 그룹 아이디 생성 방법
NHN KCP 가맹점관리자 → 결제 관리 → 자동결제 → 그룹관리를 통해 그룹 아이디를 생성합니다.
card_cert_type필수PCstring5
인증 방식입니다. 배치키 발급의 경우 BATCH로 설정합니다.ex) "card_cert_type" : "BATCH"
module_type필수PCstring2
결제창 설정 정보입니다. 01의 고정값을 사용합니다.ex) "module_type" : "01"
batch_soc필수PCstring1
NHN KCP 결제창 내에서 생년월일 사용값으로, Y로 고정합니다.ex) "batch_soc" : "Y"
good_exprPCstring가변
NHN KCP 결제창에 노출되는 제공기간 설정 변수입니다. 해당 값을 설정하지 않는 경우, 결제창에서 [자동결제]로 노출됩니다.ex) "good_expr" : "2:1m" → [1개월 자동결제]로 표기
kcp_bath_info_view필수Mobilestring1
결제창에 상품제공기간, 상품명, 금액을 노출합니다. 필수값으로 수정 불가합니다.ex) "kcp_bath_info_view" : "Y"
kcp_restricted_cardPC / Mobilestring4
배치키 발급 제한 카드구분 값 설정 변수입니다. 특정 카드에 대해 배치키 발급을 제한하려는 경우 사용합니다.
CK01 : 신용카드(Credit Card)
CK02 : 체크카드(Debit Card)
CK03 : 구매카드(Pre-paid Card)
CK04 : 기프트카드(Gift Card)ex) "kcp_restricted_card" : "CK02"
batch_soc_choicePC / Mobilestring1
NHN KCP 결제창에서 주민번호/사업자번호를 설정합니다.
S : 주민번호만 표기
C : 사업자번호만 표기ex) "batch_soc_choice" : "S"
batch_cardno_return_ynPC / Mobilestring1
배치키 발급 시 사용한 카드의 카드번호 리턴 여부를 설정합니다.
Y : 123412******1234 형식
L : 1234ex) "batch_cardno_return_yn" : "Y"
param_opt_1Mobilestring1000
NHN KCP 기본 파라미터 외 업체가 추가로 사용하는 파라미터입니다.ex) "param_opt_1" : "test"
param_opt_2Mobilestring1000
NHN KCP 기본 파라미터 외 업체가 추가로 사용하는 파라미터입니다.ex) "param_opt_2" : "test"
param_opt_3Mobilestring1000
NHN KCP 기본 파라미터 외 업체가 추가로 사용하는 파라미터입니다.ex) "param_opt_3" : "test"

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=_"
}

결제창 인증 결과 파라미터

res_cdPC / Mobilestring4
결과 코드입니다. 인증이 정상 처리되면 '0000'이 리턴됩니다.ex) "res_cd" : "0000"
res_msgPC / Mobilestring100
결과 메시지입니다.ex) "res_msg" : "정상처리"
site_cdMobilestring5
길이 5자리로 영문대문자 또는 영문대문자+숫자로 구성됩니다. 모든 서비스에 사용합니다.ex) "site_cd" : "A52Q7"
enc_dataPC / Mobilestring가변
결제창 인증 결과 암호화 정보입니다.
※ 임의로 변경할 수 없으며 결제창에서 내려 주는 값을 그대로 사용합니다.ex) "enc_data" : "SnvXdGftIEjAequorkpNhJXc4u3GRuotLHW9vyDDOhdeorM4DPXMJgJllEoRo6divo="
enc_infoPC / Mobilestring가변
결제창 인증 결과 암호화 정보입니다.
※ 임의로 변경할 수 없으며 결제창에서 내려 주는 값을 그대로 사용합니다.ex) "enc_info" : "3dsgjljlsSEGHsdccndsgnfdSDDhhbdrhffRbdfRYHFgfgnb=_"
tran_cdPC / Mobilestring8
요청 코드입니다. (수정 불가)ex) "tran_cd" : "00100000"

4. 배치키 발급 요청하기

전달받은 인증 결과 데이터(enc_data·enc_info)를 API 통신으로 배치키 발급을 요청하는 단계입니다.

배치키 발급 요청과 응답 파라미터는 API Reference > 배치키 발급을 확인하세요.

5. 배치키로 승인 요청하기

주문 정보와 발급받은 배치키를 사용해 결제 주기에 맞춰 자동결제 승인 요청합니다.
bt_group_id는 배치키 발급 단계에서 사용한 그룹아이디와 동일한 값을 사용하세요.

배치키 승인 요청과 응답 파라미터는 API Reference > 배치키 승인을 확인하세요.