자주 묻는 질문

당사에서는 개발지원센터를 통해 결제창 연동에 대한 웹가이드를 제공하고 있습니다.
"https://developer.kcp.co.kr" 접속하시어 연동가이드를 확인해 보실 수 있습니다.

Firefox, Chrome, Safari 등 웹표준을 준수하는 브라우저에서 결제 가능하며, 원활한 결제를 위해 각 브라우저의 최신버전을 권장합니다.

① PC버전 OS : 표준WEB(Windows & Mac)
② PC버전 Browser : Firefox (Ver. 27.0 ~), Chrome (Ver. 30.0 ~), Safari(Ver. 7.0 ~), Opera (Ver. 60.0~)
③ 모바일버전 OS : Android( Ver. 5.0(Lollipop) ~), IOS(Ver. 9.0 ~)
④ 모바일버전 Browser : 스마트폰 기본브라우저

다만, 각 카드사정책에 따라 카드사인증창에서 지원불가한 OS 및 브라우저가 있을 수 있습니다.

당사의 결제서비스를 이용하기 위해서는 기본적으로 아래 정보에 대해 가맹점측 방화벽 설정 상태를 확인하셔야 합니다.

① API통신 / OUTBOUND
- TEST : stg-spl.kcp.co.kr (Port : 443)
- REAL : spl.kcp.co.kr (Port : 443)

② 모바일 거래등록 / OUTBOUND
- TEST : testsmpay.kcp.co.kr (Port : 443)
- REAL : smpay.kcp.co.kr (Port : 443)

③ 입금노티수신(가상계좌 이용 시) / INBOUND
- TEST : 210.122.176.144 (Port : 80, 443)
- REAL : 103.215.144.173 / 103.215.144.174 (Port : 80, 443)

당사 테스트계 환경에서 테스트용 site_cd T0000 으로 결제하실 경우 카카오머니 외에는 실제 결제는 이루어지지 않습니다.
카카오머니 테스트 건의 경우 반드시 결제당일에 취소를 해주시기 바랍니다.

결제오류가 발생할 경우 응답코드와 응답메시지가 리턴됩니다.
사유를 확인하신 후 다시 결제를 시도하시거나 문제가 지속된다면 응답코드를 확인하시어 support@kcp.co.kr 로 문의주시기 바랍니다.

테스트 환경에서 발급된 가상계좌로 실제 입금을 하실 수 없지만 당사에서 제공해드리는 모의입금테스트페이지를 통해 모의입금 및 입금노티 수신 테스트를 하실 수 있습니다
*모의입금 테스트 페이지 : https://testadmin.kcp.co.kr/Modules/Noti/TEST_Vcnt_Noti.jsp

KCP-API 는 기본적으로 HTML javascript 와 HTTPS API 통신방식으로 구성되어 있어 특별히 개발언어의 제한은 두지 않고 있습니다.
웹페이지 구축과 서버통신이 가능한 환경이라면 KCP-API 를 연동을 하실 수 있습니다.

두 모듈간 가장 큰 차이점은 승인요청 구간에서의 통신방식이 다른점 입니다.
라이브러리방식의 경우 당사에서 제공해드린 pp_cli 통신 모듈을 가맹점 서버에 설치하여 통신하는 방식이며,
KCP-API 는 별도의 당사 라이브러리 설치 없이 HTTPS API 통신방식으로 통신합니다.

모듈 변경 시 결제창 호출 및 인증데이터 수신에 대한 부분은 변경사항 없이 기존대로 사용하시면 됩니다.
가맹점측에서 작업해주실 부분은 기존에 라이브러리를 사용하는 통신구간(결제승인, 결제취소 등)에 대해 작업을 해주시면 됩니다.

① KCP 상점관리자 -> 고객센터 -> 고객문의 -> 질문하기 통해 KCP-API 이용 신청
② KCP 상점관리자 -> 기술관리센터 -> 인증센터 -> KCP PG-API -> 개인키 및 인증서 발급
③ "2)" 발급 받은 개인키 및 인증서로 KCP-API 연동

KCP-API 연동가이드는, 당사 개발지원센터 "https://developer.kcp.co.kr" 접속하셔서 확인 가능합니다.

[오류원인]
연동한 site_cd 와 결제창 호출 환경이 다를 경우 발생.

[해결방법]
연동한 site_cd 가 테스트계 정보인지 운영계 정보인지 확인하시기 바랍니다.

① 운영계 site_cd 면 운영계 결제창 호출.
② 테스트계 site_cd 면 테스트계 결제창 호출.

- 테스트계 결제창 정보 : https://testspay.kcp.co.kr/plugin/kcp_spay_hub.js
- 운영계 결제창 정보 : https://spay.kcp.co.kr/plugin/kcp_spay_hub.js

[오류원인]
연동한 site_cd 와 site_key 정보 매칭이 되지 않을 경우 발생.

[해결방법]
① 연동한 site_cd 발급 시 수신받은 연동메일 확인하시기 바랍니다.
② 연동한 site_cd 에 대한 site_key 확인 불가 시, NHN KCP 상점관리자 -> 고객센터 -> 고객문의 -> 질문하기 통해 문의하시기 바랍니다.

[오류원인]
연동한 site_cd 에 등록되지 않은 결제수단을 연동할 경우 발생

[해결방법]
① 연동한 site_cd 에서 사용 가능한 결제수단을 확인합니다.
- 연동한 site_cd 에서 사용 가능한 결제수단 확인이 되지 않을 경우 KCP로 문의.
② pay_method 값을 정확히 입력하였는지 확인하시기 바랍니다.
- 연동가이드 참고"

[오류원인]
연동한 site_cd 에 등록되지 않은 제휴간편결제를 연동할 경우 발생

[해결방법]
연동한 site_cd 에서 사용 가능한 제휴간편결제 확인하시기 바랍니다.

[오류원인]
연동가이드 참고하시어 결제창 호출 시 site_name 값에 설정하고자 하는 명을 전달하시기 바랍니다.

[오류원인]
결제창호출 시 전달한 good_mny 와 서버통신 시 API로 전달한 결제금액검증용 금액인 ordr_mony 가 다를 경우 발생.

[해결방법]
① 결제창으로 전달한 good_mny 와 결제금액검증용 금액인 ordr_mony 가 다른 원인에 대해 확인하시기 바랍니다.
② ordr_mony 는 사용자가 변조할 수 없는 서버구간에서 전달되어야 하며, 실제 결제 처리가 되어야할 DB금액이 전달되어야 합니다.

[오류원인]
브라우저의 자동입력기능을 사용하여 결제창에서 입력 값을 자동으로 입력하여 인증요청할 경우 발생

[해결방법]
브라우저의 자동입력 설정을 해제하여 주시기 바랍니다.

[오류원인]
결제수단 pay_method 값에 오류가 있을 경우 발생

[해결방법]
pay_mehtod 의 값이 올바른 값인지 확인하시기 바랍니다.

예)
'100000000000' - 신용카드
'010000000000' - 계좌이체
'001000000000' - 가상계좌
'000100000000' - 휴대폰
'000010000000' - 상품권
'111000000000' - 신용카드/계좌이체/가상계좌

당사에서는 PC 결제모듈과 모바일 결제모듈을 별도로 제공해드리고 있습니다.
모바일 환경에서도 결제서비스를 이용하기 위해서는 모바일 결제모듈을 연동해주셔야 합니다.

웹뷰 연동 시 기본적으로 체크되어야 하는 부분에 대해 제공하고 있습니다.
모바일샘플 폴더 내 app_guide.zip 폴더 참고하시기 바랍니다.

모바일결제 모듈의 프로세스는 아래와 같습니다.


① 거래등록
- 결제에 필요한 주요 주문정보를 서버통신을 통해 안전하게 KCP로 등록요청하는 단계입니다.

② 결제창호출
- '1) 거래등록' 완료 후 리턴받은 결제창호출URL로 거래등록KEY, 주문정보를 전달하여 결제창을 호출합니다. 이때 결제창 호출은 페이지전환 방식으로 호출해주실 것을 권장드립니다. 아이프레임으로 결제창 호출 시 브라우저 보안정책으로 인해 결제가 불가할 수 있습니다.

③인증결과수신
- '카드, 실시간계좌이체' 등의 결제수단 인증완료 후 결제승인을 위해 암호화된 인증데이터를 수신받는 단계이며, 거래등록 시 가맹점에서 전달하신 ret_url 로 인증데이터가 리턴됩니다.

④ 승인요청
- ret_url 로 수신받은 암호화된 인증데이터를 KCP-API 로 승인요청하는 단계입니다.

*당사 개발지원센터에서 결제데모를 통해 테스트 해보실 수 있습니다.

[오류원인]
보안설정 및 네트워크 방화벽에 의해 발생할 수 있습니다.

[해결방법]
① 연동가이드의 KCP서버IP 정보 확인하여 방화벽 상태를 확인하시기 바랍니다..
② 가맹점 서버의 보안설정이 TLS1.2 이상 지원 가능한지 확인하시기 바랍니다..
③ 연동 환경이 PHP 라면, PHP5.3 이상을 권장합니다.

[오류원인]
가맹점의 한글인코딩 타입과 KCP의 인코딩 타입이 다를 경우 발생.

[해결방법]
연동가이드의 인코딩필터 적용해보시기 바랍니다.

안드로이드 웹뷰 연동 시 app to app 호출에 대한 처리가 되어 있지 않을 경우 발생할 수 있습니다.
app_guide.zip 내의 안드로이드 연동가이드 참고해보시기 바랍니다.

[오류원인]
모바일환경 외의 매체에서 시도

[해결방법]
useragent가 모바일(안드로이드, IOS)로 체크 될 수 있는 환경에서 결제진행 하시기 바랍니다.

[오류원인]
필수 값 누락

[해결방법]
site_cd, ordr_idxx, good_mny 등 결제창 호출 시 필수 값 확인하시기 바랍니다.

연동가이드는, 당사 개발지원센터 -> 연동하기 -> KCP-API 연동하기 -> 표준결제서비스 연동가이드 참고하시기 바랍니다.

[오류원인]
연동한 site_cd 와 결제창 호출 환경이 다른 경우

[해결방법]
① 연동한 site_cd 가 테스트계 정보인지 운영계 정보인지 확인하시기 바랍니다..
- 운영계 site_cd 면 운영계 결제창 호출.
- 테스트계 site_cd 면 테스트계 결제창 호출.

연동가이드는 당사 개발지원센터 -> 연동하기 -> KCP-API 연동하기 -> 표준결제서비스 연동가이드 참고하시기 바랍니다.

[오류원인]
올바르지 않은 site_cd 전달

[해결방법]
KCP로부터 부여 받은 site_cd 정보를 재확인하여 오타나 공백 등이 포함되어 있는지 확인하시기 바랍니다.

[오류원인]
결제창에서 카드사창 호출 후 화면 뒤로가기에 의해 발생 가능.

[해결방법]
결제창 종료 후 결제를 처음부터 다시 진행하시기 바라며, 지속적으로 문제발생 시 support@kcp.co.kr 로 문의주시기 바랍니다.

[오류원인]
거래등록 시 요청한 값과 결제창 호출 시 요청한 값이 다를 경우 발생

[해결방법]
거래등록 시 전달한 주문데이터의 정보들이 결제창 호출 시에도 정상적으로 전달 되는지 확인하시기 바랍니다.
(예. 거래등록 주문번호 A, 결제창 호출 주문번호 B 인 경우 발생.)

자동결제모듈을 연동하기 위해서는 당사와 자동결제 서비스 계약 후 연동하실 수 있습니다.
당사 영업담당자에게 요청하시거나 당사로부터 제공 받으신 상점관리자페이지 고객센터 -> 문의하기를 통해 요청하시기 바랍니다.

모바일에서도 자동결제 서비스 이용이 가능하며 모바일용 자동결제 모듈 연동이 필요합니다.

① PC 또는 모바일 배치키발급모듈을 통해 [본인인증 -> 카드인증 -> 배치키발급]
② "①"에서 발급받은 배치키를 상점 DB에 저장
③ 과금 시 배치키로 실시간 승인요청
④ 결제완료

발급된 배치키 삭제의 경우
샘플소스 상 batch_key_del.html, kcp_api_batch_key_del 페이지를 통해 진행 가능합니다.

본인인증 수단은 아래와 같습니다.

① PC자동결제모듈 : 공동인증서인증 + 카드인증
② 모바일자동결제모듈 : 휴대폰본인인증 + 카드인증

위 본인인증정보와 카드인증정보가 일치해야 배치키 발급이 가능합니다.

[오류원인]
PC자동결제모듈에서 입력한 본인인증정보와 공동인증서의 인증정보가 일치하지 않을 경우 발생


[해결방법]
PC자동결제모듈에서 입력한 인증정보(주민번호, 사업자번호)로 발급한 공동인증서가 맞는지 확인하시기 바랍니다.

[오류원인]
본인인증정보와 카드인증정보가 일치하지 않을 경우 발생

[해결방법]
① 본인인증정보와 카드발급자의 정보가 일치한지 확인하여 재시도
② 개인카드의 경우 카드소유자 생년월일정보와 본인인증수단의 생년월일정보가 일치한지 확인.
③ 기명식법인카드의 경우 카드소유자의 공동인증서나 휴대폰정보로 본인인증 진행.
④ 무기명법인카드의 경우 법인명의의 공동인증서로 본인인증 진행.

*카드정보(개인/법인) 확인이 어려울 경우 카드소지자께서 직접 카드사 고객센터로 연락하시어 확인하시기 바랍니다.

[오류원인]
카드교체발급 또는 카드분실, 카드정지 등 카드상태 변경으로 인한 발생

[해결방법]
사용하던 카드의 교체발급, 분실, 정지, 연체 등의 상태인지 확인하시기 바랍니다.

*카드상태는 카드소지자께서 직접 카드사 고객센터로 연락하시어 확인하시기 바랍니다.

[오류원인]
자동결제에 사용한 group_id 가 유효하지 않은 정보인 경우 발생

[해결방법]
정확한 group_id 정보를 확인하여 진행해주시기 바랍니다.
기발급하신 group_id 정보는 KCP 상점관리자 -> 결제관리 -> 자동결제 -> 그룹관리 메뉴에서 확인하시기 바랍니다.

[오류원인]
배치키정보와 group_id 정보가 다른 경우 발생

[해결방법]
배치키 발급 시 사용한 group_id 와 배치결제 시 사용한 group_id 정보가 동일한지 확인하시기 바랍니다.
group_id 는 배치키발급 및 결제 시 동일한 정보를 사용하셔야 합니다.

필수값이 누락된 경우 발생하는 오류이며, 누락된 파라미터명은 괄호안의 내용으로 확인 가능하니 참고 부탁드립니다.
ex) "S000 필수값 누락 (kcp_cert_in)인 경우 인증서 값 누락된 경우 입니다."

서비스인증서 정보가 올바르지 않은 경우 발생하는 오류입니다.
연동하시려는 환경에 맞게 사이트코드/서비스인증서/target_URL 이 셋팅되어있는지 확인 바랍니다.

ex) 테스트 사이트코드, 운영계 서비스인증서, 개발서버 target_URL 로 진행 시 또는
운영계 사이트코드, 테스트 서비스인증서, 운영서버 target_URL로 진행시 발생합니다.

target_URL = "https://stg-spl.kcp.co.kr/gw/enc/v1/payment"; // 개발서버
target_URL = "https://spl.kcp.co.kr/gw/enc/v1/payment"; // 운영서버

① 가맹점에 발급된 서비스인증서로 요청하지 않을 경우 발생할 수 있습니다.
kcp_cert_info 값에 가맹점 사이트코드로 발급된 서비스인증서 값을 직렬화하시어 전달해주시는지 확인 부탁드립니다.

추가로 kcp_cert_info 값에 개인키파일을 전달하고 계시진 않은지 확인 부탁드리며,
개인키파일은 kcp_sign_data를 생성하는 로직에서 경로로 참조하셔서 진행해보시기 바랍니다.

② 서비스인증서 형식이 맞지 않는 경우 오류로 kcp_cert_info 값이 올바른지 확인 부탁드립니다.
ex) kcp_cert_info 값이 null인 경우, 구분자(----BEGIN CERTIFICATE----)가 누락된 경우 등

서명데이터(kcp_sign_data)가 올바르지 않은 경우 발생하는 오류로 서명데이터(kcp_sign_data)는
거래정보를 개인키로 SHA256withRSA 알고리즘으로 인코딩해서 전달해주시기 바랍니다.

ex) kcp_sign_data 생성시 아래내용 중 mod_type 이 잘못되어있는 경우 S034 오류 발생
ORG_SIGN_DATA = T0000^20220101234567^PACA;

전체취소시에는 ORG_SIGN_DATA = T0000^20220101234567^STSC; 로,
부분취소시에는 ORG_SIGN_DATA = T0000^20220101234567^STPC; 로 전달해주시기 바랍니다.

API 통신시 필수값이 누락된 경우 발생하는 오류입니다.
필수 값이 JSON 형식으로 정상적으로 전달되는지 확인해주시기 바랍니다.

ex) tran_cd, site_cd, kcp_cert_info, enc_data, enc_info, ordr_mony

API 개발테스트에 대한 서비스인증서 및 개인키가 필요하신 경우 개발지원센터(developer.kcp.co.kr) > 기술지원 > 1:1문의하기로 당사와 계약된 사업자번호 정보와 함께 요청 문의 남겨주시면 확인 후 전달드리겠습니다.

1. order 페이지 내 site_cd값을 실운영 사이트코드로 변경
ex) T0000은 테스트서버용 사이트코드이기 때문에 계약 시 부여받은 실 운영 사이트코드로 변경해주시기 바랍니다.

2. kcp_api_page 페이지 내 target_url 운영서버로 변경
개발서버 : String target_URL = "https://stg-spl.kcp.co.kr/gw/enc/v1/payment";
운영서버 : String target_URL = "https://spl.kcp.co.kr/gw/enc/v1/payment";

3. kcp_api_page 페이지 내 서비스인증서 정보(kcp_cert_info) 변경
ex) 개발계 서비스인증서가 아닌 당사를 통해 발급받은 운영계 서비스인증서로 변경 바랍니다.

4. pc 결제창 호출 js 설정 변경(샘플소스 기준 order 페이지)
개발 : https://testspay.kcp.co.kr/plugin/kcp_spay_hub.js
운영 : https://spay.kcp.co.kr/plugin/kcp_spay_hub.js

5. 모바일 거래등록 url 설정 변경(샘플소스 기준 kcp_api_trade_reg페이지)
개발 : String target_URL = "https://stg-spl.kcp.co.kr/std/tradeReg/register";
운영 : String target_URL = "https://spl.kcp.co.kr/std/tradeReg/register";

ssl관련 오류 발생하는 것으로 예상됩니다.
가맹점 서버환경이 TLS 1.2를 지원하는 부분인지 확인 부탁드립니다. API의 경우 TLS1.2 이상에서만 진행이 가능한 점 참고 부탁드립니다.