NHN KCP
NHN KCP 결제 연동 방법을 안내합니다.

채널 설정하기
결제대행사 채널 설정하기의 내용을 참고하여 PG 설정을 진행합니다.
일반결제
가능한 결제 수단
-
결제창 일반 결제
pay_method
파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다.-
카드 :
card
-
계좌이체 :
trans
-
가상계좌 :
vbank
-
상품권 :
- 컬쳐랜드 문화상품권 :
cultureland
- 스마트 문상 :
smartculture
- 도서문화상품권 :
booknlife
- 컬쳐랜드 문화상품권 :
-
휴대폰 소액 결제 :
phone
-
간편결제 :
- 삼성페이 :
samsung
- 페이코 :
payco
- L페이 :
lpay
- 카카오페이 :
kakaopay
- 네이버페이 :
naverpay
- 애플페이 :
applepay
- 삼성페이 :
-
베네피아 포인트 :
point
-
-
결제창 빌링키 발급
pay_method
파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다.- 카드:
card
- 카드:
-
API 수기(키인) 결제
- 카드
자세한 파라미터 구성은 REST API Docs 를 참고해주시기 바랍니다.
-
API 빌링키 발급
- 카드
자세한 파라미터 구성은 REST API Docs를 참고해주시기 바랍니다.
SDK 결제 요청하기
JavaScript SDK IMP.request_pay(param, callback)
을 호출하여 NHN
KCP 결제창을 호출할 수 있습니다. 결제결과는 PC의 경우 IMP.request_pay(param, callback)
호출 후
callback 으로 수신되고
모바일의 경우 m_redirect_url 로 리디렉션됩니다.
KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
IMP.request_pay(
{
channelKey: "{콘솔 내 연동 정보의 채널키}",
pay_method: "card",
merchant_uid: "order_no_0001", //상점에서 생성한 고유 주문번호
name: "결제테스트", //주문명
amount: 1004,
company: "상호명", //해당 파라미터 설정시 통합결제창에 해당 상호명이 노출됩니다.
buyer_email: "test@portone.io",
buyer_name: "구매자이름",
buyer_tel: "010-1234-5678",
buyer_addr: "서울특별시 강남구 삼성동",
buyer_postcode: "123-456",
language: "ko", // en 입력 후 호출 시 영문으로 결제창이 표시됩니다.
m_redirect_url: "https://testtest.test", //모바일에서 결제 완료 후 리디렉션 될 URL
auth_mode: "key-in", // 키인결제(일회성 결제)이용시 설정
},
function (rsp) {
// callback 로직
//* ...중략... *//
},
);
주요 파라미터
채널키
결제를 진행할 채널을 지정합니다.
포트원 콘솔 내 [결제 연동] - [연동 정보] - [채널 관리] 에서 확인 가능합니다.
(최신 JavaScript SDK 버전부터 사용 가능합니다.)
PG사 구분코드
포트원 콘솔 내 [연동 관리] > [연동 정보] > [채널 관리] 화면에서 채널 추가 후
kcp.{mid(사이트코드)}
형식으로 채널을 지정할 때 사용됩니다.
pg
파라미터는 지원 중단 예정입니다.
JS SDK를 가장 최신 버전으로 업그레이드 후 channelKey
파라미터로 채널 설정(PG사 구분)을 대체해주세요.
결제수단 구분코드
결제 호출 시 결제수단을 지정할 때 사용됩니다.
card
(신용카드)trans
(실시간 계좌이체)vbank
(가상계좌)phone
(휴대폰 소액결제)cultureland
(컬쳐랜드 문화상품권)smartculture
(스마트문상)booknlife
(도서문화상품권)payco
(페이코)lpay
(L페이)kakaopay
(카카오페이)naverpay
(네이버페이)samsung
(삼성페이)applepay
(애플페이)point
(베네피아 포인트)
고객사 주문 고유 번호
고객사에서 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다.
결제금액
기타 파라미터
결제창에 렌더링될 카드 할부 개월수 리스트 설정값
예시코드
{
"display": {
"card_quota": [6] // 할부개월 6개월까지만 활성화
}
}
할부 개월수
예시
[]
: 일시불만 결제 가능2,3,4,5,6
: 일시불을 포함한 2, 3, 4, 5, 6개월까지 할부개월 선택 가능3
: 일시불을 포함한 2,3개월까지 할부개월 선택 가능
카드 결제시 세부 설정 정보
예시코드
{
"card": {
"direct": {
"code": "367",
"quota": 3
//카드사 포인트 사용 경우
//quota: 80 = 80(현대카드 포인트 할부개월) + 0(일시불)
//quota: 93 = 80(현대카드 포인트 할부개월) + 13개월 할부
//quota: 60 = 60(기타카드 포인트 할부개월) + 0(일시불)
//quota: 63 = 60(기타카드 포인트 할부개월) + 3개월 할부
}
},
"company": "고객사" //해당 파라미터를 설정하지 않으면 카드사 모듈 창에 iamport 로 표기
}
{
"card": {
"detail": [
{ "card_code": "*", "enabled": false }, // 모든 카드사 비활성화
{ "card_code": "366", "enabled": true } // 특정 카드만 활성화
]
}
}
카드사 렌더링 정보
카드사 코드
카드사 코드를 참고하세요.
렌더링 여부
카드사 다이렉트 호출 정보
카드사 코드
카드사 코드를 참고하세요.
고정 할부 개월수
-
일시불인 경우 0으로 입력해야 합니다.
-
카드사별 포인트 사용시 아래 할부 개월수를 더해서 요청해야 합니다.
- 현대카드 : 80개월
- 국민카드, 비씨카드, 삼성카드, 하나카드, 롯데카드, 신한카드, 농협카드, 우리카드, 씨티카드 : 60개월
앱카드 렌더링 여부
true
로 호출시 각 카드사 앱카드 결제만 활성화됩니다.
예시코드
{
"appCard": true //true 설정시 각 카드사 앱카드 결제만 활성화
}
유의사항
SDK 빌링키 발급 요청하기
JavaScript SDK IMP.request_pay(param, callback)
을 호출하여 NHN
KCP 결제창을 호출할 수 있습니다. 결제결과는 PC의 경우 IMP.request_pay(param, callback)
호출 후
callback 으로 수신되고
모바일의 경우 m_redirect_url 로 리디렉션됩니다.
빌링키 발급 요청 시에는 customer_uid
파라미터를 입력한 후 호출해야 합니다.
KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
Javascript SDKIMP.request_pay( { channelKey: "{콘솔 내 연동 정보의 채널키}", pay_method: "card", //'card'만 지원됩니다. merchant_uid: "order_monthly_0001", //상점에서 생성한 고유 주문번호 name: "정기결제", amount: 0, //결제창에 표시될 금액. 발급 요청시에는 결제가 승인되지 않습니다. customer_uid: "your-customer-unique-id", //포트원 빌링키로 필수 입력해야 합니다. buyer_email: "test@portone.io", buyer_name: "포트원", buyer_tel: "02-1234-1234", m_redirect_url: "https://testtest.test", //모바일에서 결제 완료 후 리디렉션 될 URL }, function (rsp) { if (rsp.success) { alert("빌링키 발급 성공"); } else { alert("빌링키 발급 실패"); } }, );
주요 파라미터 설명
채널키
결제를 진행할 채널을 지정합니다.
포트원 콘솔 내 [결제 연동] - [연동 정보] - [채널 관리] 에서 확인 가능합니다.
(최신 JavaScript SDK 버전부터 사용 가능합니다.)
PG사 구분코드
포트원 콘솔 내 [연동 관리] > [연동 정보] > [채널 관리] 화면에서 채널 추가 후
kcp_billing.{mid(사이트코드)}
형식으로 채널을 지정할 때 사용됩니다.
pg
파라미터는 지원 중단 예정입니다.
JS SDK를 가장 최신 버전으로 업그레이드 후 channelKey
파라미터로 채널 설정(PG사 구분)을 대체해주세요.
포트원 빌링키
빌링 결제시 사용되는 값으로 고객사에서 입력한 후 요청해야 합니다. 해당 값은 고객이 입력한 카드정보와 1:1로 매칭됩니다.
결제금액
결제창에 표시되는 금액입니다.
유의사항
API 수기(키인)결제 요청하기
수기(키인) 결제 요청시 POST /subscribe/payments/onetime
API를 호출해야 합니다.
KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
curl -H "Content-Type: application/json" \
-X POST -d '{"merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \
https://api.iamport.kr/subscribe/payments/onetime
API 빌링키 발급 요청하기
빌링키 발급 요청시 POST /subscribe/payments/onetime
또는
POST /subscribe/customers/{customer_uid}
API를 호출해야 합니다.
POST /subscribe/payments/onetime
를 호출하시는 경우 빌링키 발급과 동시에 결제가 요청됩니다.
빌링키 발급 및 결제를 원하시는 경우 customer_uid
파라미터를 필수로 입력해야 합니다.
POST /subscribe/customers/{customer_uid}
를 호출하시는 경우 빌링키만 발급됩니다.
KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
curl -H "Content-Type: application/json" \
-X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "card_number":"1234-1234-1234-1234", "expiry":"2019-01", "birth":"123456", "amount":3000}' \
https://api.iamport.kr/subscribe/payments/onetime
curl -H "Content-Type: application/json" \
-X POST -d '{"card_number":"1234-1234-1234-1234", "expiry":"2025-12", "birth":"820213", "pwd_2digit":"00"}' \
https://api.iamport.kr/subscribe/customers/your-customer-unique-id
유의사항
API 빌링키 단건 결제 요청하기
발급된 빌링키로 단건 결제를 하기 위해서는 POST /subscribe/payments/again
를 이용하여 결제를 요청해야 합니다.
KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
curl -H "Content-Type: application/json" \
-X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \
https://api.iamport.kr/subscribe/payments/again
API 빌링키 예약/반복 결제 요청하기
발급된 빌링키로 예약 결제를 하기 위해서는 POST /subscribe/payments/schedule
를 이용하여 결제를 예약합니다.
KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
server-sidecurl -H "Content-Type: application/json" \ -X POST -d '{"customer_uid":"your-customer-unique-id", "merchant_uid":"order_id_8237352", "amount":3000}' \ https://api.iamport.kr/subscribe/payments/again
퀵페이 (자체 간편 결제)
KCP 퀵페이를 연동하시는 경우 포트원 JavaScript SDK 1.2.0 이상의 버전을 사용해야 합니다.
가능한 결제 수단
- 카드 :
card
- 즉시출금 :
trans
퀵페이 호출하기
퀵페이의 경우 결제 기능을 포함하여 결제수단 등록 및 삭제, PIN 번호 변경 및 초기화, 탈퇴 기능을 지원합니다.
KCP 퀵페이 기준으로 작성한 예시 코드는 아래와 같습니다.
IMP.request_pay(
{
channelKey: "{콘솔 내 연동 정보의 채널키}",
pay_method: "card", //즉시 출금 이용 시 'trans' 입력
merchant_uid: "order_no_0001", //상점에서 생성한 고유 주문번호
name: "결제수단 등록테스트", //주문명
amount: 0, //등록시 0으로 전달
buyer_email: "test@portone.io",
buyer_name: "구매자이름",
buyer_tel: "010-1234-5678",
buyer_addr: "서울특별시 강남구 삼성동",
buyer_postcode: "123-456",
customer_uid: "use_your_unique_id_with_pay_method_0", //결제 수단에 대한 고유 식별값
bypass: {
kcpQuick: {
//KCP퀵페이 설정 정보
actionType: "Register", //결제수단 등록
memberCI: "djkDFJ45dFndkl", //본인인증 후 전달된 CI 값
memeberID: "use_your_unique_id", //사용자에 대한 고유 식별값
},
},
m_redirect_url: "https://testtest.test", //결제수단 등록 후 리디렉션될 URL
},
function (rsp) {
// callback 로직
//* ...중략... *//
},
);
IMP.request_pay(
{
channelKey: "{콘솔 내 연동 정보의 채널키}",
pay_method: "card", //즉시 출금 이용 시 'trans' 입력
merchant_uid: "order_no_0001", //상점에서 생성한 고유 주문번호
name: "결제수단 삭제테스트", //주문명
amount: 0, //삭제시 0으로 전달
buyer_email: "test@portone.io",
buyer_name: "구매자이름",
buyer_tel: "010-1234-5678",
buyer_addr: "서울특별시 강남구 삼성동",
buyer_postcode: "123-456",
customer_uid: "use_your_unique_id_with_pay_method_0", //결제 수단에 대한 고유 식별값
bypass: {
kcpQuick: {
//KCP퀵페이 설정 정보
actionType: "Deregister", //결제수단 삭제
memberCI: "djkDFJ45dFndkl", //결제수단 등록시 입력한 CI 값
memeberID: "use_your_unique_id", //사용자에 대한 고유 식별값
},
},
m_redirect_url: "https://testtest.test", //결제수단 등록 후 리디렉션될 URL
},
function (rsp) {
// callback 로직
//* ...중략... *//
},
);
IMP.request_pay(
{
channelKey: "{콘솔 내 연동 정보의 채널키}",
pay_method: "card", //즉시 출금 이용 시 'trans' 입력
merchant_uid: "order_no_0001", //상점에서 생성한 고유 주문번호
name: "결제 테스트", //주문명
amount: 1000,
buyer_email: "test@portone.io",
buyer_name: "구매자이름",
buyer_tel: "010-1234-5678",
buyer_addr: "서울특별시 강남구 삼성동",
buyer_postcode: "123-456",
customer_uid: "use_your_unique_id_with_pay_method_0", //결제 수단에 대한 고유 식별값
bypass: {
kcpQuick: {
//KCP퀵페이 설정 정보
actionType: "Pay", //결제 요청
memberCI: "djkDFJ45dFndkl", //결제수단 등록시 입력한 CI 값
memeberID: "use_your_unique_id", //사용자에 대한 고유 식별값
},
},
m_redirect_url: "https://testtest.test", //결제수단 등록 후 리디렉션될 URL
},
function (rsp) {
// callback 로직
//* ...중략... *//
},
);
IMP.request_pay(
{
channelKey: "{콘솔 내 연동 정보의 채널키}",
pay_method: "card", //즉시 출금 이용 시 'trans' 입력
merchant_uid: "order_no_0001", //상점에서 생성한 고유 주문번호
name: "PIN번호 변경 테스트", //주문명
amount: 0, //pin번호 변경시 0으로 전달
buyer_email: "test@portone.io",
buyer_name: "구매자이름",
buyer_tel: "010-1234-5678",
buyer_addr: "서울특별시 강남구 삼성동",
buyer_postcode: "123-456",
customer_uid: "use_your_unique_id", //memberId와 동일하게 입력
bypass: {
kcpQuick: {
//KCP퀵페이 설정 정보
actionType: "PinChange", //PIN번호 변경
memberCI: "djkDFJ45dFndkl", //결제수단 등록시 입력한 CI 값
memeberID: "use_your_unique_id", //사용자에 대한 고유 식별값
},
},
m_redirect_url: "https://testtest.test", //결제수단 등록 후 리디렉션될 URL
},
function (rsp) {
// callback 로직
//* ...중략... *//
},
);
IMP.request_pay(
{
channelKey: "{콘솔 내 연동 정보의 채널키}",
pay_method: "card", //즉시 출금 이용 시 'trans' 입력
merchant_uid: "order_no_0001", //상점에서 생성한 고유 주문번호
name: "PIN번호 초기화 테스트", //주문명
amount: 0, //pin번호 초기화시 0으로 전달
buyer_email: "test@portone.io",
buyer_name: "구매자이름",
buyer_tel: "010-1234-5678",
buyer_addr: "서울특별시 강남구 삼성동",
buyer_postcode: "123-456",
customer_uid: "use_your_unique_id", //memberId와 동일하게 입력
bypass: {
kcpQuick: {
//KCP퀵페이 설정 정보
actionType: "PinReset", //PIN번호 초기화
memberCI: "djkDFJ45dFndkl", //결제수단 등록시 입력한 CI 값
memeberID: "use_your_unique_id", //사용자에 대한 고유 식별값
},
},
m_redirect_url: "https://testtest.test", //결제수단 등록 후 리디렉션될 URL
},
function (rsp) {
// callback 로직
//* ...중략... *//
},
);
IMP.request_pay(
{
channelKey: "{콘솔 내 연동 정보의 채널키}",
pay_method: "card", //즉시 출금 이용 시 'trans' 입력
merchant_uid: "order_no_0001", //상점에서 생성한 고유 주문번호
name: "전화번호 변경 테스트", //주문명
amount: 0, //사용자만 등록시 0으로 전달
buyer_email: "test@portone.io",
buyer_name: "구매자이름",
buyer_tel: "010-1234-5678",
buyer_addr: "서울특별시 강남구 삼성동",
buyer_postcode: "123-456",
customer_uid: "use_your_unique_id", //memberId와 동일하게 입력
bypass: {
kcpQuick: {
//KCP퀵페이 설정 정보
actionType: "PhoneChange", //등록된 휴대폰 번호 변경
memberCI: "djkDFJ45dFndkl", //본인인증 후 전달된 CI 값
memeberID: "use_your_unique_id", //사용자에 대한 고유 식별값
},
},
m_redirect_url: "https://testtest.test", //결제수단 등록 후 리디렉션될 URL
},
function (rsp) {
// callback 로직
//* ...중략... *//
},
);
IMP.request_pay(
{
channelKey: "{콘솔 내 연동 정보의 채널키}",
pay_method: "card", //즉시 출금 이용 시 'trans' 입력
merchant_uid: "order_no_0001", //상점에서 생성한 고유 주문번호
name: "해지 테스트", //주문명
amount: 0, //해지시 0으로 전달
buyer_email: "test@portone.io",
buyer_name: "구매자이름",
buyer_tel: "010-1234-5678",
buyer_addr: "서울특별시 강남구 삼성동",
buyer_postcode: "123-456",
customer_uid: "use_your_unique_id", //memberId와 동일하게 입력
bypass: {
kcpQuick: {
//KCP퀵페이 설정 정보
actionType: "Terminate", //유저 및 결제수단 삭제
memberCI: "djkDFJ45dFndkl", //본인인증 후 전달된 CI 값
memeberID: "use_your_unique_id", //사용자에 대한 고유 식별값
},
},
m_redirect_url: "https://testtest.test", //결제수단 등록 후 리디렉션될 URL
},
function (rsp) {
// callback 로직
//* ...중략... *//
},
);
퀵페이의 경우 m_redirect_url시 다음과 같이 4개의 파라미터가 Query String으로 전달됩니다.
imp_uid
merchant_uid
imp_status
: true 또는 falsekcp_action
: Register 또는 Dregister 또는 Pay
kcp_action
이 Register 이고 imp_status
가 true인 경우 결제수단 등록에 성공하였다는 것을 의미합니다.
주요 파라미터
채널키
결제를 진행할 채널을 지정합니다.
포트원 콘솔 내 [결제 연동] - [연동 정보] - [채널 관리] 에서 확인 가능합니다.
(최신 JavaScript SDK 버전부터 사용 가능합니다.)
PG사 구분코드
포트원 콘솔 내 [연동 관리] > [연동 정보] > [채널 관리] 화면에서 채널 추가 후
kcp_quick.{mid(사이트코드)}
형식으로 채널을 지정할 때 사용됩니다.
pg
파라미터는 지원 중단 예정입니다.
JS SDK를 가장 최신 버전으로 업그레이드 후 channelKey
파라미터로 채널 설정(PG사 구분)을 대체해주세요.
결제수단 구분코드
결제 호출 시 결제수단을 지정할 때 사용됩니다.
- card (카드)
- trans (즉시출금)
고객사 주문 고유 번호
고객사에서 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다.
결제금액
결제 수단에 대한 고유 식별값
퀵페이에 등록된 결제수단과 1:1 맵핑됩니다.
PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음
KCP 퀵페이 설정정보
퀵페이 결제시 필수로 입력해야 합니다.
호출 유형
- Register : 결제 수단 등록
- Deregister : 결제 수단 삭제
- Pay : 결제
- PinChange : PIN번호 변경
- PinReset : PIN번호 초기화
- PhoneChange : 전화번호 변경
- Terminate : 결제 수단 해지
본인인증 CI값
사용자 식별값
최대 16byte까지 입력가능하며, 고객이 여러개의 결제수단을 등록하는 경우 동일한 memberID
를 입력해야 합니다.
디바이스 식별값
미 입력시 고객이 사용한 브라우저 정보가 입력됩니다.
무인증 등록/결제 여부
true
로 입력한 경우 무인증 키가 발급되며, 이후 결제시 PIN번호 인증 과정이 생략됩니다.
- true : 무인증 결제
- false : 인증 결제
할부 개월수
입력하지 않는 경우 일시불로 진행됩니다.
카드사 포인트 결제 여부
입력하지 않는 경우 미사용으로 진행됩니다.
- true : 카드사 포인트 사용
- false : 카드사 포인트 미사용