NHN KCP
NHN KCP 연동 방법을 안내합니다.
채널 설정하기
- 결제대행사 채널 설정하기의 내용을 참고하여 PG 설정을 진행합니다.
사전 계약 안내
아래 기능을 사용하시려면 KCP에 사전 신청 후 계약이 완료되어야 합니다. 그렇지 않은 상태에서 해당 기능 이용시 결제 승인에 실패하거나, 승인에 성공하더라도 의도한 바와는 다른 응답(ex. 결제창에서 에스크로 결제를 했으나 비-에스크로 결제 응답을 받음)을 얻게 될 수 있으니 주의해주시기 바랍니다.
- API를 통한 수기 결제 (가상계좌, 카드)
- API를 통한 빌링키 발급
- 에스크로 결제
- 상점분담무이자 설정
- 부가세 및 비과세 금액 직접 설정
- 부분무이자 설정
- 휴대폰 결제 익월 환불
가능한 결제 수단
-
결제창 일반 결제
payMethod
파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다.- 카드 :
CARD
- 계좌이체 :
TRANSFER
- 가상계좌 :
VIRTUAL_ACCOUNT
- 상품권 :
GIFT_CERTIFICATE
- 휴대폰 소액 결제 :
MOBILE
- 간편결제 :
EASY_PAY
- 카드 :
-
결제창 빌링키 발급
billingKeyMethod
파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다.- 카드:
CARD
- 카드:
-
API 수기(키인) 결제
method
파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다.- 카드:
card
로 설졍하여 카드 관련 파라미터 입력 - 가상계좌:
virtualAccount
로 설정하여 가상계좌 관련 파라미터 입력
자세한 파라미터 구성은 REST API Docs 를 참고해주시기 바랍니다.
- 카드:
-
API 빌링키 발급
method
파라미터를 결제 수단에 따라 아래와 같이 설정해야 합니다.- 카드:
card
로 설졍하여 카드 관련 파라미터 입력
자세한 파라미터 구성은 REST API Docs를 참고해주시기 바랍니다.
- 카드:
SDK 결제 요청하기
결제 요청 시에는 requestPayment
함수를 호출해야 합니다.
channelKey
파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 KCP 채널 사용을 명시해주세요.
KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
import * as PortOne from "@portone/browser-sdk/v2";
function requestPayment() {
PortOne.requestPayment({
storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요.
channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
paymentId: `payment${crypto.randomUUID()}`,
orderName: "나이키 와플 트레이너 2 SD",
totalAmount: 1000,
currency: "CURRENCY_KRW",
payMethod: "CARD",
customer: {
fullName: "포트원",
phoneNumber: "010-0000-1234",
email: "test@portone.io",
},
});
}
주요 파라미터
-
storeId
* string스토어 아이디
포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다.
-
paymentId
* string고객사 주문 고유 번호
고객사에서 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다. 이미 승인 완료된
paymentId
로 결제를 시도하는 경우 에러가 발생합니다. KCP의 경우 최대 40자 까지 허용합니다. -
orderName
* string주문명
주문명으로 고객사에서 자유롭게 입력합니다. KCP의 경우 최대 100Byte까지 허용합니다.
-
channelKey
* string채널 키
포트원 콘솔 내 [연동 관리] > [연동 정보] > [채널 관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다.
-
totalAmount
* number결제 금액
결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다.
-
currency
* string결제 통화
결제통화로 원화 결제 시
KRW
로 입력해야 합니다. -
payMethod
* string결제수단 구분코드
결제 호출 시 결제수단을 지정할 때 사용됩니다.
- 신용카드 :
CARD
- 실시간 계좌이체 :
TRANSFER
- 가상계좌 :
VIRTUAL_ACCOUNT
- 휴대폰 소액결제 :
MOBILE
- 간편 결제 :
EASY_PAY
- 신용카드 :
-
customer
object고객 정보
-
fullName
string구매자 전체 이름
-
firstName
string구매자 이름
-
lastName
string구매자 성
-
phoneNumber
string구매자 연락처
-
email
string구매자 이메일
-
-
bypass
oneof objectPG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음
-
kcp_v2
objectKCP에서 제공하는 파라미터 모음
-
site_logo
string결제창에 삽입할 메인 로고 url
- 결제창 왼쪽 상단에 표시됩니다.
- 이미지 사이즈는 150*50 미만으로 설정해야 하며, GIF, JPG 파일만 지원됩니다.
-
skin_indx
integer결제창 색상
- PC로 결제창 호출 시 결제창 색상을 변경합니다.
- 1~12까지 설정 가능합니다.
-
kcp_pay_title
string결제창 상단 문구
- 결제창의 상단 문구를 변경합니다.
-
shop_user_id
string기관에 따라 리스크 관리 조치를 위한 쇼핑몰 관리 ID
- 상품권, 휴대폰 결제 시 필수로 입력해야 합니다.
-
site_name
string카드사 다이렉트 호출 시 결제창에 표기될 상호명
- PC의 경우 신한, 현대, 삼성, 농협, 하나, 외환, 롯데, 씨티, 우리카드사에 대해 다이렉트 호출 시 필수로 입력해야 합니다.
- 모바일의 경우 필수로 입력해야 합니다.
-
disp_tax_yn
string결제창 현금영수증 노출 여부
- 결제창에서 현금영수증 노출 여부를 설정할 수 있습니다. 실시간 계좌이체 또는 가상계좌 결제 시 사용할 수 있습니다.
Y
: 노출N
: 노출하지 않음R
: 소득공제로 노출E
: 지출증빙으로 노출
-
deli_term
string에스크로 결제 예상 배송 소요일
- 에스크로 결제 시, 결제 상품의 예상 배송 소요일입니다. KCP측에서 에스크로 결제 사용 시 입력을 권장하고 있습니다.
- 미입력 시 '00'으로 입력됩니다.
- 입력 형식은 두 자리 수로 입력되어야 합니다. ex. 예상 배송 소요기간이 3일인 경우,
03
으로 입력
-
-
예제
bypass 파라미터 예시{ "bypass": { "kcp_v2": { "site_logo": "https://portone.io/assets/portone.jpg", "skin_indx": 6, "shop_user_id": "user_id1", "site_name": "포트원 고객사" } } }
SDK 결제 - 유의사항
공통
카드 결제
간편 결제
계좌이체
가상계좌 결제
상품권 결제
휴대폰 소액 결제
에스크로 결제
SDK 빌링키 발급 요청하기
빌링키 발급 요청 시에는 requestIssueBillingKey
함수를 호출해야 합니다.
channelKey
파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 KCP 채널 사용을 명시해주세요.
KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
import * as PortOne from "@portone/browser-sdk/v2";
function requestIssueBillingKey() {
PortOne.requestIssueBillingKey({
storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요.
channelKey: "channel-key-3b37819a-1c72-4deb-a245-8c810af5403d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
billingKeyMethod: "CARD",
issueId: "test-issueId",
issueName: "test-issueName",
customer: {
fullName: "포트원",
phoneNumber: "010-0000-1234",
email: "test@portone.io",
},
});
}
주요 파라미터
-
storeId
* string스토어 아이디
포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다.
-
channelKey
* string채널 키
포트원 콘솔 내 [연동 관리] > [연동 정보] > [채널 관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다.
-
billingKeyMethod
* string빌링키 발급수단
KCP는 빌링키 발급 수단으로 카드만을 지원하므로 해당 파라미터는
CARD
로 고정해야 합니다. -
issueId
* string빌링키 발급 건 고유 ID
- 고객사에서 채번하여 사용해야 합니다.
- KCP의 경우 필수 입력해야 합니다. // 추후 수정 필요, 포트원 내부 채번으로 수정할 예정
-
issueName
* string빌링키 발급 시 결제창에 표시되는 제목
- 모바일 발급의 경우 필수 입력해야 합니다.
-
customer
object고객 정보
-
fullName
string구매자 전체 이름
-
firstName
string구매자 이름
-
lastName
string구매자 성
-
phoneNumber
string구매자 연락처
-
email
string구매자 이메일
-
-
offerPeriod
object제공 기간
-
bypass
oneof objectPG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음
-
kcp_v2
objectKCP에서 제공하는 파라미터 모음
-
batch_soc_choice
'percard' | 'cocard'결제창에서 주민번호/사업자 번호 고정여부 설정
- S: 주민번호만 표시
- C: 사업자번호만 표시
-
-
SDK 빌링키 발급 - 유의사항
API 수기(키인)결제 요청하기
수기(키인) 결제 요청 시 POST /payments/${PAYMENT_ID_HERE}/instant
API를 호출해야 합니다.
KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
// ... 수기(키인) 결제
const issueResponse = await axios({
url: `https://api.portone.io/payments/${PAYMENT_ID_HERE}/instant`,
method: "post",
headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
data: {
channelKey: "channel-key-9987cb87-****-****-****-********896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
orderName: "나이키 와플 트레이너 2 SD",
amount: {
total: 10000,
},
currency: "KRW",
customer: {
name: {
full: "홍길동",
},
email: "test@test.com",
phoneNumber: "010-1234-0000",
},
method: {
card: {
credential: {
nuber: "1234123400001234", // 카드 번호 입력 시 숫자만 입력해주세요.
expiryYear: "26", // 유효기간 만료 연도 2자리
expiryMonth: "12", // 유효기간 만료 월 2자리
birthOrBusinessRegistrationNumber: "900101", // 카드 소유주 생년월일 또는 사업자 등록번호
passwordTwoDigits: "00", // 카드 비밀번호 앞 2자리
},
},
},
},
});
// ... 수기(키인) 결제
const issueResponse = await axios({
url: `https://api.portone.io/payments/${PAYMENT_ID_HERE}/instant`,
method: "post",
headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
data: {
channelKey: "channel-key-9987cb87-****-****-****-********896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
orderName: "나이키 와플 트레이너 2 SD",
amount: {
total: 10000,
},
currency: "KRW",
customer: {
name: {
full: "홍길동",
},
email: "test@test.com",
phoneNumber: "010-1234-0000",
},
method: {
virtualAccount: {
bank: `SHINHAN`,
expiry: {
dueDate: `2024-11-12T00:00:00+09+00`, //입금기한은 미래시간만 가능합니다.
},
cashReceipt: {
type: `PERSONAL`,
customerIdentityNumber: `010-1234-0000`,
},
remitteeName: `테스트`,
},
},
},
});
주요 파라미터
-
paymentId
* string고객사 주문 고유 번호
고객사에서 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다. 이미 승인 완료된
paymentId
로 결제를 시도하는 경우 에러가 발생합니다. KCP의 경우 최대 40자까지 허용합니다. -
orderName
* string주문명
주문명으로 고객사에서 자유롭게 입력합니다. KCP의 경우 최대 100 바이트까지 허용합니다.
-
channelKey
* string채널 키
포트원 콘솔 내 [연동 관리] > [연동 정보] > [채널 관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다.
-
amount
* object결제 금액
-
total
* number총 결제 금액
결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다.
-
taxFree
number면세액
결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다.
-
-
currency
* string결제 통화
결제통화로 원화 결제 시
KRW
로 입력해야 합니다. -
method
* object결제수단 정보
-
virtualAccount
object가상계좌 결제 시 파라미터
-
bank
* string발급 은행
- 은행코드는 ENUM으로 정의되어 있습니다.
- BANK ENUM 바로가기
-
expiry
* object입금 만료 기한
validHours
또는dueDate
필드 중 하나를 지정합니다.-
validHours
integer유효 시간
-
dueDate
string만료 시점
시간은 RFC 3339 date-time 형식으로 입력해야 합니다.
-
-
option
* object가상계좌 발급 방식
-
type
* string가상계좌 발급 유형 회전식 가상계좌만 지원하므로
NORMAL
로 입력합니다.
-
-
cashReceipt
* object현금영수증 정보
-
type
* string발급 유형
PERSONAL
또는CORPORATE
로 입력합니다.- 소득공제용 :
PERSONAL
- 지출증빙용 :
CORPORATE
- 소득공제용 :
-
customerIdentityNumber
* string현금영수증 식별 번호
- 소득공제인 경우 주민등록번호 혹은 휴대폰 번호를 입력해야 합니다.
- 지출증빙인 경우 사업자등록번호를 입력해야 합니다.
-
-
-
card
object카드 결제 시 파라미터
-
credential
* string인증 관련 정보
-
number
* object카드 번호
-
expiryYear
* object유효 기간 만료 연도 (YY 형식 ex. 24)
-
expiryMonth
* string유효기간 만료 월 (MM 형식 ex. 05)
-
birthOrBusinessRegistrationNumber
* string생년월일 또는 사업자 등록 번호
-
passwordTwoDigits
* string비밀번호 앞 두자리
-
-
-
-
customer
object고객 정보
-
name
object고객 이름
-
full 또는 separated 중 하나를 입력할 수 있습니다.
-
full
string한 줄 이름 형식 (ex. 김포트)
-
separated
object분리된 이름
-
first
* string이름
-
last
* string성
-
-
-
-
phoneNumber
string구매자 연락처
-
email
string구매자 이메일
-
유의사항
카드 결제
가상계좌 결제
API 빌링키 발급 요청하기
빌링키를 발급 요청 시 POST /billing-keys
를 호출해야 합니다.
KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
const issueResponse = await axios({
url: "https://api.portone.io/billing-keys",
method: "post",
headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
data: {
channelKey: "channel-key-9987cb87-****-****-****-********896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
customer: {
id: "customer-1234", // 고객사에서 관리하는 고객 고유번호
},
method: {
card: {
credential: {
number: "1111111111111111",
expiryMonth: "01",
expiryYear: "20",
birthOrBusinessRegistrationNumber: "900101",
passwordTwoDigits: "00",
},
},
},
},
});
주요 파라미터
-
channelKey
* string채널 키
포트원 콘솔 내 [연동 관리] > [연동 정보] > [채널 관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다.
-
method
* object결제수단 정보
-
card
object카드 빌링키 발급 시 파라미터
-
credential
string인증 관련 정보
-
number
* object카드 번호
-
expiryYear
* object유효 기간 만료 연도 (YY 형식 ex. 24)
-
expiryMonth
* string유효기간 만료 월 (MM 형식 ex. 05)
-
birthOrBusinessRegistrationNumber
string -
KCP의 경우 필수로 입력해야 합니다.
-
passwordTwoDigits
string비밀번호 앞 두자리
-
KCP의 경우 필수로 입력해야 합니다.
-
-
-
-
customer
* object고객 정보
-
name
* object고객 이름
-
full
string한 줄 이름 형식 (ex. 김포트)
-
separated
object분리된 이름
-
first
* string이름
-
last
* string성
-
-
-
phoneNumber
* string구매자 연락처
-
email
* string구매자 이메일
-
API 빌링키 단건 결제 요청하기
발급된 빌링키로 단건 결제 요청 시 POST /payments/${PAYMENT_ID_HERE}/billing-key
API를 호출해야 합니다.
KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
const response = await axios({
url: `https://api.portone.io/payments/${PAYMENT_ID_HERE}/billing-key`,
method: "post",
headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
data: {
payment: {
billingKey: "billing-key-1", // 빌링키 발급 API를 통해 발급받은 빌링키
orderName: "후불 결제",
customer: {
id: "customer-1234", // 고객사에서 관리하는 고객 고유번호
phoneNumber: "010-1234-5678",
email: "test@test.com",
},
amount: {
total: 10000,
},
currency: "KRW",
},
},
});
주요 파라미터
-
paymentId
* string결제 주문 번호
- 고객사에서 채번하여 사용하는 주문번호로 고유한 값이여야 합니다.
- URL path에 포함하여 요청해야 합니다.
-
billingKey
* string빌링키 결제에 사용할 빌링키
-
orderName
* string주문명
-
amount
* object결제 금액
-
total
* number총 결제 금액
결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다.
-
taxFree
number면세액
결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다.
-
-
currency
* string결제 통화
결제통화로 원화 결제 시
KRW
로 입력해야 합니다. -
customer
* object고객 정보
-
name
* object고객 이름
-
full
string한 줄 이름 형식 (ex. 김포트)
-
separated
object분리된 이름
-
first
* string이름
-
last
* string성
-
-
-
phoneNumber
* string구매자 연락처
-
email
* string구매자 이메일
-
-
productCount
integer상품 개수
API 빌링키 예약/반복 결제 요청하기
예약 결제를 하기 위해서는 POST /payments/${PAYMENT_ID_HERE}/schedule
를 이용하여 결제를 예약합니다.
KCP 기준으로 작성한 예시 코드는 아래와 같습니다.
const response = await axios({
url: `https://api.portone.io/payments/${PAYMENT_ID_HERE}/schedule`,
method: "post",
headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
data: {
payment: {
billingKey: "billing-key-1", // 빌링키 발급 API를 통해 발급받은 빌링키
orderName: "월간 이용권 정기결제",
customer: {
id: "customer-1234", // 고객사에서 관리하는 고객 고유번호
},
amount: {
total: 10000,
},
currency: "KRW",
},
timeToPay: "2023-01-01T00:00:00+09:00", // 결제 예정 시점. RFC 3339 형식으로 입력해야 합니다.
},
});
주요 파라미터
-
paymentId
* string결제 주문 번호
- 고객사에서 채번하여 사용하는 주문번호로 고유한 값이여야 합니다.
- URL path에 포함하여 요청해야 합니다.
-
payment
* object빌링키 결제 요청 입력정보
-
billingKey
* string빌링키 결제에 사용할 빌링키
-
orderName
* string주문명
-
amount
* object결제 금액
-
total
* number총 결제 금액
결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다.
-
taxFree
number면세액
결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다.
-
-
currency
* string결제 통화
결제통화로 원화 결제 시
KRW
로 입력해야 합니다. -
customer
* object고객 정보
-
name
* object고객 이름
-
full
string한 줄 이름 형식 (ex. 김포트)
-
separated
object분리된 이름
-
first
* string이름
-
last
* string성
-
-
-
phoneNumber
* string구매자 연락처
-
email
* string구매자 이메일
-
-
-
timeToPay
* string결제 예정 시점