Guide > 표준결제
표준결제
표준결제
표준결제 서비스 연동하기
고객이 표준 결제 창을 통해 신용카드, 계좌이체 휴대폰 등 결제수단별 인증과정을 진행하고 HTTPS API 통신을 이용해 NHN KCP로 승인요청 및 승인 응답을 처리하는 서비스입니다.
표준결제 서비스 과정
1. 서비스 인증서 적용하기
서비스 인증서는 가맹점 인증과 부인 방지를 위해 API 결제 서비스에서 사용돼요.
NHN KCP는 가맹점이 전달한 서비스 인증서 정보를 검증하고, 해당 결제 요청에 대한 결과를 응답합니다.
✅ 휴대폰 결제는 Guide > 휴대폰 결제에서 확인해 주세요.
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":"CARD",
"Ret_URL":"https://쇼핑몰주문처리서버/../return"
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_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":"100000000000",
"ordr_idxx":"TEST123456789",
"good_name":"운동화",
"good_mny":"1000"
}
결제창 호출 파라미터
site_cd필수PC / Mobile
길이 5자리로 영문대문자 또는 영문대문자+숫자로 구성됩니다.
모든 서비스에 사용합니다.
ex) "site_cd" : "T0000"
pay_method필수PC / Mobile
MOBILE 결제수단 코드 값 입니다. (4 Byte)
신용카드 : CARD
계좌이체 : BANK
휴대폰 : MOBX
포인트 : TPNT
상품권 : GIFT
ex) "pay_method" : "CARD"
PC 결제수단 코드 값 입니다. (12 Byte)
신용카드 : 100000000000
계좌이체 : 010000000000
포인트 : 000100000000
휴대폰 : 000010000000
상품권 : 000000001000
ex) "pay_method" : "100000000000"
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 / 달러 - 840
※ PC 원화 - WON / 달러 - USD
ex) 모바일의 경우, "currency" : "410"
shop_user_id필수PC / Mobile
휴대폰, 상품권 결제시 필수 파라미터입니다.
쇼핑몰에서 관리하는 회원 ID
※ 유니크한 값으로 입력
기관에 따라 리스크 관리 조치를 위한 쇼핑몰 관리 ID를 필수로 요청
ex) "shop_user_id" : "hong123"
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"
van_code필수Mobile
상품권, 포인트 결제시 필수 파라미터입니다.
도서문화 상품권 - SCBL
컬쳐랜드 상품권 - SCCL
베네피아 복지 포인트 - SCWB
OK캐쉬백 - SCSK
ex) "van_code" : "SCBL"
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"
신용카드 전용 옵션파라미터
quotaoptPC / Mobile
50,000원 이상 거래에 대한 할부 옵션. 기본값은 12개월. 0~12의 값을 설정하면 결제 창에 할부 개월 수가 최대값까지 표기됩니다.
ex) "quotaopt" : "12"
kcp_nointPC / Mobile
상점 부담 무이자 설정
"" : 상점관리자 설정에 따름
"Y" : kcp_noint_quota 값에 따라 무이자표시(단, 상점관리자에 설정이 되어야 함)
"N" : 상점관리자 값을 무시하고 일반할부로 처리됨
ex) "kcp_noint" : "Y"
kcp_noint_quotaPC / Mobile
상점 부담 무이자 카드사 설정
무이자 적용할 대상 카드코드와 할부개월수 무이자 설정은 카드사 별로 설정 가능
ex) "kcp_noint_quota" : "CCBC-02:03:06, CCSS-03:06"
used_card_YNPC
결제창에 노출할 카드사 설정
※ 해당 변수 값을 Y로 설정 후 used_card 변수 값에 원하는 신용카드사의 코드를 입력
※ 입력한 신용카드사만 결제 창에 노출
ex) "used_card_YN" : "Y"
used_cardPC / Mobile
결제창에 노출할 카드사
ex) "used_card" : "CCBC:CCKM:CCSS"
fix_instPC / Mobile
결제금액이 50,000원 이상일 경우 결제 창에서 선택 할 수 있는 할부 개월 수를 0~12 의 값 중 하나로 고정
ex) "fix_inst" : "0"
휴대폰 추가 설정 파라미터
used_mobxPC / Mobile
결제창에 노출할 통신사
원하는 통신사만 노출시킬수 있습니다.
ex) "used_mobx" : "SKT:KTF:LGT"
포인트 추가 설정 파라미터
pt_memcorp_cdPC / Mobile
베네피아(SK M&C)에서 발급한 회원소속사코드로 베네피아 복지포인트를 사용한다면 필수로 처리됩니다.
테스트계는 null로 설정해주시고, 운영계는 회원소속사코드로 설정해주시기 바랍니다.
ex) "pt_memcorp_cd" : "회원소속사코드"
complex_pnt_ynPC / Mobile
포인트 결제 시 결제 금액의 일부를 신용카드 결제와 함께 사용 가능합니다.
complex_pnt_yn 을 ‘N’으로 설정하면 포인트로만 결제 이루어집니다.
ex) "complex_pnt_yn" : "N"
추가옵션 파라미터
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. 결제창 인증 결과
결제창에서 인증을 진행한 후 인증에 대한 결과를 응답받습니다.
응답 파라미터 중 enc_info, enc_data는 인증 정보를 암호화한 값으로 리턴된 그대로 결제 요청해 주세요.
결제창 인증 주요 파라미터
{
"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. 결제창 승인요청
전달받은 인증결과 데이터(enc_data, enc_info)를 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":"PACA",
"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
실제 결제수단(결제수단 유효성 검증)
가맹점 서버에 저장된 결제수단에 값을 입력해주세요.
신용카드 : PACA
계좌이체 : PABK
휴 대 폰 : PAMC
포 인 트 : PAPT
상 품 권 : PATK
ex) "pay_type" : "PACA"
6. 결제창 승인응답
결제승인에 성공하면 res_cd 파라미터에 “0000” 응답코드 리턴과 함께 결제수단별 응답파라미터에 값이 채워져서 리턴됩니다.
결과 응답 데이터를 확인하시어 결제수단별 결과값들을 가맹점 서버에 저장 및 관리하시기 바랍니다.
✅ 결제 승인 응답에 대한 과정은 API Reference를 확인해 주세요.
//신용카드 응답 데이터 예시
{
"res_cd":"0000",
"res_msg":"정상처리",
"pay_method":"PACA",
"order_no":"TEST123456789",
"amount":"1000",
"card_mny":"1000",
"coupon_mny":"0",
"card_no":"4673090000000032",
"quota":"00",
"tno":"24346915432487",
"card_cd":"CCKM",
"card_name":"국민카드",
"app_no":"78710726"
}