표준결제
표준결제 서비스 연동하기
신용카드나 계좌이체 등 고객이 선택한 결제수단별로 인증을 진행한 뒤,
HTTPS API 통신을 이용해 NHN KCP 측에 결제 승인을 요청하고 응답을 처리하는 서비스입니다.
표준결제 특징
결제창 UI 제공
KCP가 제공하는 결제창을 호출만 하면 되어, 가맹점이 별도로 결제 UI를 개발할 필요가 없습니다.
다양한 결제수단
신용카드·계좌이체·휴대폰·포인트·상품권을 pay_method 파라미터를 통해 결제창에 노출합니다.
PC·Mobile 지원
PC와 Mobile을 모두 지원합니다. Mobile 환경에서는 결제창 호출 전에 거래등록을 먼저 진행합니다.
표준결제 서비스 과정
1. Mobile 거래등록 하기
Mobile 환경에서는 결제창 호출 전, 주문·결제 정보를 미리 NHN KCP 결제 서버에 등록하는 거래등록이 필요합니다.
거래등록 응답으로 받은 approval_key·PayUrl을 결제창 호출 시 사용합니다.
2. 결제창 호출하기
거래등록 후, 결제수단 인증과 결제 요청을 위해 결제창을 호출합니다.
PC와 Mobile 환경에 따라 호출 방식이 다릅니다.


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(); }
<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되는 스크립트 종료 예외 */ } }
<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"
}결제창 호출 파라미터
신용카드 : CARD
계좌이체 : BANK
휴대폰 : MOBX
포인트 : TPNT
상품권 : GIFT
ex) "pay_method" : "CARD"
PC 결제수단 코드 값입니다. (12 Byte)
신용카드 : 100000000000
계좌이체 : 010000000000
포인트 : 000100000000
휴대폰 : 000010000000
상품권 : 000000001000
ex) "pay_method" : "100000000000"
※ 거래등록 시 전송한 Ret_URL 값과 동일한 값을 결제창 호출 form에도 함께 전송해야 합니다.
※ 콜백 응답 Body는 EUC-KR로 인코딩되어 전달되므로, 가맹점 서버에서 디코딩 처리가 필요합니다.ex) "Ret_URL" : "https://your-shop.example.com/return"
※ 기관에 따라 리스크 관리 조치를 위한 쇼핑몰 관리 ID를 필수로 요청ex) "shop_user_id" : "hong123"
신용카드 전용 옵션 파라미터
"" : 가맹점관리자 설정에 따릅니다.
"Y" : kcp_noint_quota 값에 따라 무이자로 표시됩니다. (가맹점관리자에 설정되어 있어야 합니다.)
"N" : 가맹점관리자 값을 무시하고 일반 할부로 처리됩니다.ex) "kcp_noint" : "Y"
이 값을 Y로 설정한 뒤 used_card에 노출할 신용카드 코드를 입력하면, 입력한 신용카드만 결제창에 노출됩니다.ex) "used_card_YN" : "Y"
휴대폰 추가 설정 파라미터
휴대폰 결제는 Guide > 휴대폰 결제를 확인하세요.ex) "used_mobx" : "SKT:KTF:LGT"
포인트 추가 설정 파라미터
도서문화상품권: SCBL, 컬쳐랜드: SCCL, OK 캐쉬백: SCSK, 베네피아복지포인트: SCWB
상품권 추가 설정 파라미터
도서문화상품권: SCBL, 컬쳐랜드: SCCL, OK 캐쉬백: SCSK, 베네피아복지포인트: SCWB
추가옵션 파라미터
- 로고 파일은 GIF, JPG 파일만 지원합니다.
- 최대 크기는 150 X 50 미만입니다.
- 이미지 파일을 150 X 50 이상으로 설정하거나 이 파라미터를 생략하면 site_name 값이 표시됩니다.
※ site_logo 설정 시 결제창 호출이 느려질 수 있습니다.ex) "site_logo" : "https://test.kcp.co.kr/logo.jpg"
"", "0" : 일반결제
"1" : 제공기간
※ 기본값은 일반결제입니다.ex) "good_expr" : "0"
※ 복합과세 전용 사이트코드로 계약한 가맹점에만 해당합니다.ex) "comm_tax_mny" : "909"
※ 복합과세 전용 사이트코드로 계약한 가맹점에만 해당합니다.ex) "comm_free_mny" : "0"
※ 복합과세 전용 사이트코드로 계약한 가맹점에만 해당합니다.ex) "comm_vat_mny" : "91"
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=_"
} 결제창 인증 결과 파라미터
※ 임의로 변경할 수 없으며 결제창에서 내려 주는 값을 그대로 사용합니다.ex) "enc_data" : "SnvXdGftIEjAequorkpNhJXc4u3GRuotLHW9vyDDOhdeorM4DPXMJgJllEoRo6divo="
※ 임의로 변경할 수 없으며 결제창에서 내려 주는 값을 그대로 사용합니다.ex) "enc_info" : "3dsgjljlsSEGHsdccndsgnfdSDDhhbdrhffRbdfRYHFgfgnb=_"
4. 결제 승인 요청하기
전달받은 인증 결과 데이터(enc_data·enc_info)를 API 통신으로 결제 승인 요청하는 단계입니다.
승인 요청 전에는 결제창에서 받은 인증 결과와 실제 승인 요청 값이 일치하는지 확인하기 위해
결제 금액(ordr_mony)·주문번호(ordr_no)·결제수단(pay_type)을 함께 전달하여 결제정보를 검증하세요.
5. 결제 승인 응답
결제 승인에 성공하면 res_cd에 0000이 리턴되고, 결제수단별 응답 파라미터에 값이 채워져 함께 리턴됩니다.
응답 데이터를 확인해 결제수단별 결과 값을 가맹점 서버에 저장·관리하세요.