전담지원 신청
Guide > 표준결제

표준결제

표준결제 서비스 연동하기

신용카드나 계좌이체 등 고객이 선택한 결제수단별로 인증을 진행한 뒤,
HTTPS API 통신을 이용해 NHN KCP 측에 결제 승인을 요청하고 응답을 처리하는 서비스입니다.

표준결제 특징

결제창 UI 제공

KCP가 제공하는 결제창을 호출만 하면 되어, 가맹점이 별도로 결제 UI를 개발할 필요가 없습니다.

다양한 결제수단

신용카드·계좌이체·휴대폰·포인트·상품권을 pay_method 파라미터를 통해 결제창에 노출합니다.

PC·Mobile 지원

PC와 Mobile을 모두 지원합니다. Mobile 환경에서는 결제창 호출 전에 거래등록을 먼저 진행합니다.

표준결제 서비스 과정

고객
가맹점
NHN KCP
기관
(은행, 카드사)
거래등록은 Mobile 만 해당하는 단계입니다.
서버 통신
서버 통신

1. Mobile 거래등록 하기

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

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

2. 결제창 호출하기

거래등록 후, 결제수단 인증과 결제 요청을 위해 결제창을 호출합니다.
PC와 Mobile 환경에 따라 호출 방식이 다릅니다.

Mobile 결제창
Mobile 결제창
PC 결제창
PC 결제창

Mobile 결제창 호출

Mobile 환경에서는 거래등록 후 call_pay_form 함수를 호출합니다.
거래등록 응답에서 리턴된 PayUrl(결제창 호출 주소)에 order_info를 전달해 결제창을 띄웁니다.

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 결제창 호출 폼 파라미터 (order_info)
<form name="order_info" method="post" action="PayUrl">
{
	"site_cd":"T0000",
	"pay_method":"CARD",
	"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",
	"good_name":"운동화",
	"good_mny":"1000",
	"good_cd":"00"
}

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":"T0000",
	"site_name":"NHN KCP",
	"currency":"410",
	"pay_method":"100000000000",
	"ordr_idxx":"TEST123456789",
	"good_name":"운동화",
	"good_mny":"1000",
	"good_cd":"00"
}

결제창 호출 파라미터

site_cd필수PC / Mobilestring5
NHN KCP가 발급한 사이트(가맹점) 코드입니다. 모든 서비스에 동일하게 사용됩니다.ex) "site_cd" : "T0000"
pay_method필수PC / Mobilestring412
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필수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"
AppUrlMobilestring가변
외부 인증 앱에서 가맹점 앱으로 복귀하기 위한 URL Scheme입니다. Mobile 앱에서 결제할 때 입력합니다.ex) "AppUrl" : "myapp://"
ordr_idxx필수PC / Mobilestring50
가맹점에서 관리하는 주문번호입니다. 중복되지 않는 유니크한 값으로 사용하고, 가맹점에서 반드시 저장합니다.ex) "ordr_idxx" : "TEST123456789"
good_mny필수PC / Mobilenumber12
결제 금액입니다. 콤마·소수점 없이 숫자만 입력합니다.ex) "good_mny" : "1000"
good_name필수PC / Mobilestring100
상품명입니다.ex) "good_name" : "운동화"
good_cdPC / Mobilestring20
상품코드입니다. 주문상품명으로 구분이 어려운 경우, 상품군을 따로 구분하여 처리할 수 있는 기능입니다.ex) "good_cd" : "00"
currency필수PC / Mobilestring3
결제 통화 코드입니다. 원화(KRW)는 410, 미국 달러(USD)는 840을 사용합니다.ex) "currency" : "410"
shop_user_id필수PC / Mobilestring50
쇼핑몰에서 관리하는 회원 ID입니다. 휴대폰, 상품권 결제 시 필수 파라미터이며 유니크한 값으로 사용합니다.
※ 기관에 따라 리스크 관리 조치를 위한 쇼핑몰 관리 ID를 필수로 요청ex) "shop_user_id" : "hong123"
buyr_namePC / Mobilestring40
주문자 이름입니다.ex) "buyr_name" : "홍길동"
buyr_mailPC / Mobilestring100
주문자 이메일입니다. 결제 결과 메일 발송 등에 사용됩니다.ex) "buyr_mail" : "test@your-shop.example.com"
buyr_tel2PC / Mobilestring20
주문자 휴대폰 번호입니다. 하이픈(-)을 포함할 수 있습니다.ex) "buyr_tel2" : "010-1234-1234"
shop_nameMobilestring20
가맹점(사이트)명입니다. 결제창과 영수증에 노출됩니다.ex) "shop_name" : "NHN KCP SHOP"
site_name필수PCstring20
사이트명입니다.ex) "site_name" : "NHN KCP"

신용카드 전용 옵션 파라미터

quotaoptPC / Mobilestring2
50,000원 이상 거래에 적용하는 할부 옵션입니다. 기본값은 12개월이며, 0~12 사이로 설정하면 결제창에 해당 개월 수까지 할부가 표기됩니다.ex) "quotaopt" : "12"
kcp_nointPC / Mobilestring1
가맹점 부담 무이자 여부를 설정합니다.
"" : 가맹점관리자 설정에 따릅니다.
"Y" : kcp_noint_quota 값에 따라 무이자로 표시됩니다. (가맹점관리자에 설정되어 있어야 합니다.)
"N" : 가맹점관리자 값을 무시하고 일반 할부로 처리됩니다.ex) "kcp_noint" : "Y"
kcp_noint_quotaPC / Mobilestring256
가맹점이 부담하는 무이자를 카드사별로 설정합니다. 무이자를 적용할 카드코드와 할부 개월 수를 카드사별로 지정할 수 있습니다.ex) "kcp_noint_quota" : "CCBC-02:03:06, CCSS-03:06"
used_card_YNPCstring1
결제창에 노출할 카드사를 직접 지정할지 설정합니다.
이 값을 Y로 설정한 뒤 used_card에 노출할 신용카드 코드를 입력하면, 입력한 신용카드만 결제창에 노출됩니다.ex) "used_card_YN" : "Y"
used_cardPC / Mobilestring256
결제창에 노출할 카드사를 지정합니다.ex) "used_card" : "CCBC:CCKM:CCSS"
fix_instPCstring2
결제 금액이 50,000원 이상일 때 결제창에서 선택할 수 있는 할부 개월 수를 0~12 중 하나로 고정합니다.ex) "fix_inst" : "0"

휴대폰 추가 설정 파라미터

used_mobxPC / Mobilestring30
결제창에 노출할 통신사를 지정합니다. 원하는 통신사만 노출시킬 수 있습니다.
휴대폰 결제는 Guide > 휴대폰 결제를 확인하세요.ex) "used_mobx" : "SKT:KTF:LGT"

포인트 추가 설정 파라미터

van_code필수Mobilestring4
결제 추가 수단입니다.
도서문화상품권: SCBL, 컬쳐랜드: SCCL, OK 캐쉬백: SCSK, 베네피아복지포인트: SCWB
pt_memcorp_cd필수PC / Mobilestring4
베네피아 소속사 코드입니다. 베네피아 포인트 결제 시 필수로 전달합니다.ex) "pt_memcorp_cd" : "5555"
complex_pnt_ynPC / Mobilestring1
포인트 결제 시 결제 금액의 일부를 신용카드 결제와 함께 사용할 수 있습니다. 이 값을 'N'으로 설정하면 포인트로만 결제됩니다.ex) "complex_pnt_yn" : "N"

상품권 추가 설정 파라미터

van_code필수Mobilestring4
결제 추가 수단입니다.
도서문화상품권: SCBL, 컬쳐랜드: SCCL, OK 캐쉬백: SCSK, 베네피아복지포인트: SCWB

추가옵션 파라미터

site_logoPCstring256
결제창 왼쪽 상단에 가맹점 사이트의 로고를 노출합니다.
- 로고 파일은 GIF, JPG 파일만 지원합니다.
- 최대 크기는 150 X 50 미만입니다.
- 이미지 파일을 150 X 50 이상으로 설정하거나 이 파라미터를 생략하면 site_name 값이 표시됩니다.
※ site_logo 설정 시 결제창 호출이 느려질 수 있습니다.ex) "site_logo" : "https://test.kcp.co.kr/logo.jpg"
eng_flagPCstring1
결제창을 한글 또는 영문으로 변환합니다.ex) 영문일 경우, "eng_flag" : "Y"
skin_indxPCstring2
결제창 스킨을 변경합니다. 1~12까지 설정할 수 있습니다.ex) "skin_indx" : "1"
good_exprPCstring1
상품 제공기간을 설정합니다.
"", "0" : 일반결제
"1" : 제공기간
※ 기본값은 일반결제입니다.ex) "good_expr" : "0"
comm_tax_mnyPC / Mobilenumber12
공급가액입니다. (공급가액 = good_mny / 1.1)
※ 복합과세 전용 사이트코드로 계약한 가맹점에만 해당합니다.ex) "comm_tax_mny" : "909"
comm_free_mnyPC / Mobilenumber12
비과세액입니다.
※ 복합과세 전용 사이트코드로 계약한 가맹점에만 해당합니다.ex) "comm_free_mny" : "0"
comm_vat_mnyPC / Mobilenumber12
부가가치세입니다. (부가가치세 = good_mny − 과세 공급가액 − 비과세액)
※ 복합과세 전용 사이트코드로 계약한 가맹점에만 해당합니다.ex) "comm_vat_mny" : "91"
kcp_pay_titlePCstring30
결제창 상단에 노출할 문구입니다.ex) "kcp_pay_title" : "NHN KCP 결제의 중심"
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" : "정상처리"
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 통신으로 결제 승인 요청하는 단계입니다.
승인 요청 전에는 결제창에서 받은 인증 결과와 실제 승인 요청 값이 일치하는지 확인하기 위해
결제 금액(ordr_mony)·주문번호(ordr_no)·결제수단(pay_type)을 함께 전달하여 결제정보를 검증하세요.

결제정보 검증 기능은 결제정보 검증을 확인하세요.

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

5. 결제 승인 응답

결제 승인에 성공하면 res_cd에 0000이 리턴되고, 결제수단별 응답 파라미터에 값이 채워져 함께 리턴됩니다.
응답 데이터를 확인해 결제수단별 결과 값을 가맹점 서버에 저장·관리하세요.