Guide > 휴대폰 결제
휴대폰 결제
휴대폰 결제
휴대폰 결제 연동하기
NHN KCP 표준결제 서비스 중 휴대폰 결제 연동에 특화된 가이드입니다.
휴대폰 결제는 통신사에서 제공하는 결제 한도를 활용해 상품이나 서비스를 구매하는 방식입니다.
결제된 금액은 다음 달 휴대폰 요금에 함께 청구되며, 카드나 계좌 없이 휴대폰 번호만으로 간편하게 이용할 수 있어요.
✅ 휴대폰 결제 취소
휴대폰 결제의 경우 통신사 정책으로 결제 발생 당월에만 취소가 가능합니다.
취소 가능 기간이 지나면 KCP를 통한 환불이 불가하며, 가맹점 자체 환불을 진행하셔야 합니다.
예) 5월 31일 결제 > 6월 1일 취소 불가
신용카드, 계좌이체, 상품권, 포인트 등 다른 결제수단은 표준결제 서비스 연동 가이드를 참고해 주세요.
휴대폰 결제 과정
1. 서비스 인증서 적용하기
서비스 인증서는 가맹점 인증과 부인 방지를 위해 API 결제 서비스에서 사용돼요.
NHN KCP는 가맹점이 전달한 서비스 인증서 정보를 검증하고, 해당 결제 요청에 대한 결과를 응답합니다.
✅ 서비스 인증서에 대한 자세한 내용은 API Reference의 KCP PG-API를 확인해 주세요.
2. Mobile 거래등록 하기
모바일 버전에서는 결제 요청할 데이터 중 주문 및 결제 정보를 미리 NHN KCP 결제 서버에 등록하는 거래 등록이 필수입니다.
데이터 검증을 위해 결제 요청 전, 가맹점의 주문 요청 데이터를 서버에 저장해 주세요.
필수 주문 정보인 ordr_idxx, good_mny, pay_method, Ret_URL 파라미터의 값은 반드시 가맹점 서버에 저장하여 사용해 주세요.
🔗 거래등록 API Reference 바로가기
3. 결제창 호출하기
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":"CARD",
"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_Execute_Web 함수로 전달하여 결제창을 호출합니다.
KCP_Pay_Execute_Web 함수는 JS로 불러온 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":"100000000000",
"ordr_idxx":"TEST123456789",
"good_name":"운동화",
"good_cd":"00",
"good_mny":"1000"
}
결제창 호출 파라미터
site_cd필수PC / Mobile
길이 5자리로 영문대문자 또는 영문대문자+숫자로 구성됩니다.
모든 서비스에 사용합니다.
ex) "site_cd" : "T0000"
pay_method필수PC / Mobile
MOBILE 결제수단 코드 값 입니다. (4 Byte)
휴대폰 : MOBX
ex) "pay_method" : "MOBX"
PC 결제수단 코드 값 입니다. (12 Byte)
휴대폰 : 000010000000
ex) "pay_method" : "000010000000"
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" : "운동화"
good_cdPC / Mobile
상품코드
주문상품명으로 구분이 어려운 경우 상품군을 따로 구분하여 처리할 수 있는 기능
ex) "good_cd" : "00"
currency필수PC / Mobile
화폐단위
※ Mobile 원화 - 410 / 달러 - 840
※ PC 원화 - WON / 달러 - USD
ex) 모바일의 경우, "currency" : "410"
buyr_namePC / Mobile
주문자이름
ex) "buyr_name" : "홍길동"
buyr_mailPC / Mobile
주문자 이메일
입력하신 E-Mail 주소로 결제 결과 메일이 발송됩니다.
buyr_tel2PC / Mobile
주문자 휴대폰번호
하이폰(-)포함 가능
ex) "buyr_tel2" : "010-1234-1234"
shop_nameMobile
사이트명
ex) "shop_name" : "NHN KCP SHOP"
site_namePC
상점이름(영문으로 작성권장)
ex) "site_name" : "NHN KCP"
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"
휴대폰 옵션 파라미터
used_mobxPC / Mobile
결제창에 노출할 통신사
원하는 통신사만 노출시킬수 있습니다.
ex) "used_mobx" : "SKT:KTF:LGT"
추가옵션 파라미터
site_logo PC
결제 창 왼쪽 상단에 가맹점 사이트의 로고를 띄움니다.
업체의 로고가 있는 URL을 정확히 입력해야 하며 해당 변수 생략 시에는 로고가 뜨지 않고 site_name 값이 표시됨
로고 파일은 GIF, JPG 파일만 지원
최대 사이즈 : 150 X 50 미만
이미지 파일을 150 X 50 이상으로 설정 시 site_name 값이 표시됨
※ site_logo 설정 시 결제 창 호출이 느려질 수 있음
ex) "site_logo" : "https://test.kcp.co.kr/logo.jpg"
eng_flagPC / Mobile
결제 창 한글/영문 변환
ex) 영문일 경우, "eng_flag" : "Y"
skin_indx PC
결제 창 스킨 변경. 1~12까지 설정 가능
ex) "skin_indx" : "1"
good_expr PC
상품 제공기간
"", "0" : 일반결제
"1" : 제공기간
※ 기본 설정은 일반결제
ex) "good_expr" : "0"
tax_flagPC / Mobile
복합 과세 구문
TG03 : 복합과세
ex) "tax_flag" : "TG03"
comm_tax_mnyPC / Mobile
공급가액
공급가액 = good_mny / 1.1
ex) "comm_tax_mny" : "909"
comm_free_mnyPC / Mobile
비과세액
ex) "comm_free_mny" : "0"
comm_vat_mnyPC / Mobile
부가가치세
부가가치세 = good_mny – 과세 공급가액 - 비과세액
ex) "comm_vat_mny" : "91"
kcp_pay_title PC
결제창 상단 문구
ex) "kcp_pay_title" : "NHN KCP 결제의 중심"
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. 결제창 인증 결과
결제창에서 PASS 인증과 일반 인증 중, 인증 방식 진행 후 인증에 대한 결과를 응답받습니다.
응답 파라미터 중 enc_info, enc_data 는 인증 정보를 암호화한 값으로, 리턴된 그대로 결제 요청해 주세요.
PASS 인증: 통신사 PASS 앱을 이용해 본인 여부를 확인하는 인증 방식으로, 비밀번호나 생체인증으로 간편하게 인증할 수 있습니다.
SMS 인증: 휴대폰 번호로 전송된 인증번호를 입력해 본인 여부를 확인하는 가장 일반적인 인증 방식입니다.
결제창 인증 주요 파라미터
{
"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"
ordr_idxxPC / Mobile
상점에서 관리하는 주문번호입니다. 중복되지 않는 유니크한 값으로 사용하시길 권장합니다.
주문 데이터 관리를 위해 가맹점에서 반드시 저장해야합니다.
ex) "ordr_idxx" : "TEST123456789"
buyr_nameMobile
주문자이름
ex) "buyr_name" : "홍길동"
buyr_mailMobile
주문자 이메일
입력하신 E-Mail 주소로 결제 결과 메일이 발송됩니다.
buyr_tel2Mobile
주문자 휴대폰번호
하이폰(-)포함 가능
ex) "buyr_tel2" : "010-1234-1234"
5. 결제창 승인요청
Ret_URL로 전달받은 인증 결과 데이터를 API 통신으로 결제승인을 요청하는 단계입니다.
승인요청 데이터는 NHN KCP가 제공하는 API URL로 json string 형태로 전송해주세요.
단, 승인요청 하기 전에 결제창으로부터 받은 인증결과 데이터와 승인요청하는 데이터가 일치하는지 검증하기 위해
실제 결제금액인 ordr_mony, ordr_no, pay_type을 서버 통신으로 넘겨주시기 바랍니다.
결제창에서 처리된 정보와 서버단으로 요청하는 정보가 일치하지 않으면 거절처리를 할 수 있도록 지원하는 기능이니,
결제정보 검증기능 적용을 참고 바랍니다.
✅ 결제정보 검증 기능 참고사항바로가기
{
"tran_cd":"00100000",
"kcp_cert_info" : "-----BEGIN CERTIFICATE-----MIIDgTCCAmmgAwIBAgIHkiG9w0……-----END CERTIFICATE-----",
"site_cd":"T0000",
"enc_data":"SnvXdGftIEjAequorkpNhJXc4hfghdfs5dfsgu3GRuotLHW9vyDDOhdeorM4DPXMJgJlIEoRo6divo=",
"enc_info":"3dsgjljlsSEGHsdccndsgnfdSDDhhbdrhffRbdfRYHFgfgnb=_",
"ordr_mony":"1000",
"pay_type":"PAMC",
"ordr_no":"TEST123456789"
}
승인 요청 파라미터
site_cd필수PC / Mobile
길이 5자리로 영문대문자 또는 영문대문자+숫자로 구성됩니다.
모든 서비스에 사용합니다.
ex) "site_cd" : "T0000"
kcp_cert_info필수PC / Mobile
NHN KCP 에서 발급하는 서비스 인증서로, 상점관리자의 인증센터에서 다운받은 pem 파일내용을 직렬화 하여 사용합니다.
모든 서비스에 사용합니다.
ex) "kcp_cert_info" : "-----BEGIN CERTIFICATE-----MIIDgTCCAmmgAwIBAgIHkiG9w0…………Cay7pJNWXCnw4jIiBsTBa3q95RVRyMEcDgPwugMXPXGBwNoMOOpuQ==-----END CERTIFICATE-----"
enc_data필수PC / Mobile
결제창 인증결과 암호화 정보
통합 결제 창으로부터 전달 받는 인증결과 암호화 데이터
※ 절대 임의로 변경 불가하며 결제 창에서 내려 주는 값을 그대로 사용 부탁 드립니다.
ex) "enc_data" : "1eOSNbDDMQCVqCHVNZGNPKZErG2lCPBL24RTDIATPEXWERwBkrN4ghC4M0ue81I8y-LZ1tl6q8CMpw-LvpFdQDKzbHx5tx1OYWBf"
enc_info필수PC / Mobile
결제창 인증결과 암호화 정보
통합 결제 창으로부터 전달 받는 인증결과 암호화 데이터
※ 절대 임의로 변경 불가하며 결제 창에서 내려 주는 값을 그대로 사용 부탁 드립니다.
ex) "enc_info" : "4dgxMICIupJdwMheYKVQI.Vd6cKDpBSSkWfEfW1k431UaMlGzuVl1N.NIsrbdDnQ5i9Mu.JVz.C7JIK1NpdfDkdYd"
tran_cd필수PC / Mobile
요청코드(수정불가)
ex) "tran_cd" : "00100000"
ordr_mony필수PC / Mobile
실제 결제 요청 금액(결제금액 유효성 검증)
ex) "ordr_mony" : "1000"
ordr_no필수PC / Mobile
실제 결제 주문번호
ex) "ordr_no" : "TEST123456789"
pay_type필수PC / Mobile
실제 결제수단(결제수단 유효성 검증)
가맹점 서버에 저장된 결제수단에 값을 입력해주세요.
휴 대 폰 : PAMC
ex) "pay_type" : "PAMC"
6. 결제창 승인응답
결제승인에 성공하면 res_cd 파라미터에 “0000” 응답코드 리턴과 함께 결제수단별 응답파라미터에 값이 채워져서 리턴됩니다.
결과 응답 데이터를 확인하시어 결제수단별 결과값들을 가맹점 서버에 저장 및 관리하시기 바랍니다.
✅ 결제 승인 응답에 대한 과정은 API Reference를 확인해 주세요.