스마트 라우팅 - 연동하기
멀티PG 환경을 클릭 한 번으로 쉽게 만들 수 있는 결제 트래픽 분산 자동화 서비스 입니다.
스마트 라우팅 기능이 궁금하다면 스마트 라우팅 기능 소개를 확인해 보세요!
스마트 라우팅을 이용하시려면 관리자콘솔에서 스마트 라우팅 그룹을 먼저 설정해야합니다. 그룹 설정 방법이 궁금하다면 스마트 라우팅 그룹 설정 가이드를 확인해 보세요.
SDK(결제창) 인증결제 연동하기
SDK를 이용하는 경우 결제 호출 시 생성한 스마트 라우팅 그룹의 ID를 전용 파라미터인 channelGroupId
에
지정하여 사용이 가능합니다.
이 외에 다른 결제 기능들은 기존과 동일하게 사용이 가능합니다. 단, 결제대행사 별로 지원하는 기능이 다를 수 있으니
그룹 내에서 사용하는 모든 결제대행사에서 지원하는 기능만 사용하시길 권장드립니다.
인증결제와 관련된 자세한 내용은 인증 결제 연동하기 문서를 참고하시기 바랍니다.
예제 코드
//포트원 인증결제 SDK 호출
PortOne.requestPayment({
storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec",
// 결제대행사를 지정할 때 사용한 channelKey 대신
// channelGroupId 파라미터에 스마트 라우팅 그룹 ID를 설정합니다.
channelGroupId: "channel-group-live-f042e8e2-92f1-4f68-ad61-cec6ede41529",
// 기타 인증결제 파라미터 설정
paymentId: `payment-${crypto.randomUUID()}`,
orderName: "나이키 와플 트레이너 2 SD",
totalAmount: 1000,
currency: "CURRENCY_KRW",
payMethod: "CARD",
// 스마트 라우팅 사용 시 필수 파라미터 추가 설정
customer: {
fullName: "홍길동",
phoneNumber: "010-1234-5678",
email: "test@test.com",
},
});
주요 파라미터
channelGroupId
* string
스마트 라우팅 그룹 ID
-
관리자 콘솔의 [연동 관리] → [스마트 라우팅] 메뉴에서 확인할 수 있습니다.
-
스마트 라우팅 그룹 ID를 지정하여 결제창을 호출하면, 스마트 라우팅 그룹 내 설정된 채널 비율에 따라 확률 기반으로 하나의 결제대행사가 호출됩니다.
필수 파라미터
각 파라미터에 대한 상세한 설명은 결제요청 파라미터 문서를 참고하시기 바랍니다.
-
storeId
* string고객사 ID
-
paymentId
* string고객사 주문 고유 번호
-
orderName
* string주문명
-
totalAmount
* number결제 금액
-
currency
* string결제 통화
-
payMethod
* string결제수단 구분코드
-
virtualAccount
object가상계좌 결제 사용 시 필요한 파라미터입니다.
-
accountExpiry
* object가상계좌 입금 만료기한
스마트 라우팅을 이용한 가상계좌 결제 사용 시 필수 입력해야 합니다.
-
validHours
number가상계좌 입금 유효 시간
-
dueDate
string가상계좌 입금 유효 시각
-
-
-
easyPay
object간편결제 정보
스마트 라우팅을 이용한 간편결제 다이렉트 호출 시 필수 입력해야 합니다.
-
easyPayProvider
string간편결제 수단
-
-
productType
* string상품 유형
스마트 라우팅을 이용한 휴대폰 소액결제 사용 시 필수 입력해야 합니다.
-
customer
* object구매자 정보
-
fullName
* string구매자 전체 이름
fullName
파라미터 대신firstName
과lastName
파라미터를 사용해도 됩니다. -
phoneNumber
* string구매자 연락처
-
email
* string구매자 이메일 주소
-
기타 파라미터는 결제요청 파라미터 문서를 참고하시길 바립니다.
유의사항
API 수기(키인)결제 연동하기
API를 이용하는 경우 결제 호출 시 생성한 스마트 라우팅 그룹의 ID를 전용 파라미터인 channelGroupId
에
지정하여 사용이 가능합니다.
이 외에 다른 결제 기능들은 기존과 동일하게 사용이 가능합니다. 단, 결제대행사 별로 지원하는 기능이 다를 수 있으니
그룹 내에서 사용하는 모든 결제대행사에서 지원하는 기능만 사용하시길 권장드립니다.
수기(키인)결제와 관련된 자세한 내용은 수기(키인)결제 연동하기 문서를 참고하시기 바랍니다.
예제 코드
// 포트원 수기(키인)결제 API 호출
const paymentResponse = await fetch(
`https://api.portone.io/payments/${encodeURIComponent(UNIQUE_PAYMENT_ID)}/instant`,
{
method: "POST",
headers: {
Authorization: `PortOne ${PORTONE_API_SECRET}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
// channelGroupId 파라미터에 스마트 라우팅 그룹 ID를 설정합니다.
channelGroupId: "channel-group-test-94ab2b51-b7e1-4b74-9a9c-9fb6e117a6ac",
orderName: "월간 이용권 정기결제",
// 수기 결제 API를 참고해 고객 정보를 채워주세요.
customer: {
name: {
full: "김포트", // 고객 이름을 입력해야 합니다.
},
},
amount: {
total: 8900,
},
currency: "KRW",
// 수기(키인)결제 API를 참고해 카드 / 가상계좌 정보를 채워주세요.
method: {
card: {
credential: {
number: "0000123400001234", // 16자리 숫자만 입력해야 합니다.
expiryYear: "26", // 연도의 뒤 2자리를 입력해야 합니다.
expiryMonth: "12",
birthOrBusinessRegistrationNumber: "900101", // 생년월일 6자리 또는 사업자 등록번호 10자리를 입력해야 합니다.
passwordTwoDigits: "00", // 카드 비밀번호 앞 2자리 입력해야 합니다.
},
},
},
productType: "PHYSICAL", // 상품이 실물인 경우 `PHYSICAL`, 디지털인 경우 `DIGITAL` 입력해야 합니다.
}),
},
);
if (!paymentResponse.ok)
throw new Error(`paymentResponse: ${await paymentResponse.json()}`);
주요 파라미터
channelGroupId
* string
스마트 라우팅 그룹 ID
-
관리자 콘솔의 [연동 관리] → [스마트 라우팅] 메뉴에서 확인할 수 있습니다.
-
스마트 라우팅 그룹 ID를 지정하여 결제창을 호출하면, 스마트 라우팅 그룹 내 설정된 채널 비율에 따라 확률 기반으로 하나의 결제대행사가 호출됩니다.
필수 파라미터
-
paymentId
* string고객사 주문 고유 번호
-
orderName
* string주문명
-
amount
* object주문 금액
-
total
* number결제 금액
-
-
currency
* string결제 통화
-
customer
* object구매자 정보
-
name
* object구매자 이름
-
full
* string구매자 전체 이름
full
파라미터 대신separated.first
와separated.last
파라미터로 사용해도 됩니다.
-
-
phoneNumber
* string구매자 연락처
가상계좌 발급 시 필수 입력해야 합니다.
-
email
* string구매자 이메일 주소
가상계좌 발급 시 필수 입력해야 합니다.
-
-
method
* object결제 수단
-
card
* object카드 결제
-
credential
* object카드 정보
-
number
* string카드 번호
-
expiryYear
* string카드 유효기간 중 연도
-
expiryMonth
* string카드 유효기간 중 월
-
birthOrBusinessRegistrationNumber
* string생년월일 또는 사업자번호
-
passwordTwoDigits
* string카드 비밀번호 앞 2자리
-
-
-
virtualAccount
* object가상 계좌
-
bank
* object은행 정보
-
expiry
* object만료 기한
-
dueDate
* string만료 시점
-
-
option
* object가상계좌 발급 방식
-
type
* string가상계좌 발급 유형
일반 가상계좌 (회전식)인 경우
NOMAL
를 입력해야 합니다.
-
-
cashReceipt
* object현금영수증 정보
-
type
* string현금영수증 발급 유형
-
customerIdentityNumber
* string현금영수증 발급 식별 정보
-
-
remitteeName
* string가상계좌 예금주명
-
-
-
productType
* string상품 유형
KSNET로 카드 결제시에만 MID 설정 정보와 검증을 진행합니다. 다른 PG사 결제 요청시에는 별도로 검증하지 않습니다.
-
productCount
* string상품 개수
스마트로로 가상계좌 발급시에만 정보가 유효합니다. 다른 PG사 결제 요청시에는 별도로 검증하지 않습니다.
유의사항
API 빌링키 발급 및 정기결제 연동하기
빌링키 발급 API 호출 시 생성한 스마트 라우팅 그룹의 ID를 전용 파라미터인 channelGroupId
에
지정하여 사용이 가능합니다.
channelGroupId
를 지정하여 빌링키 발급 요청 시 그룹 내 모든 채널로 빌링키 발급을 시도합니다.
이후 발급된 결제대행사의 빌링키가 모두 포트원 빌링키에 맵핑됩니다.
스마트 라우팅 기능을 이용하여 발급된 포트원 빌링키는 슈퍼빌링키라고 부릅니다.
해당 빌링키로 빌링키 결제 또는 예약결제 API를 이용하여 결제 요청 시 해당 스마트 라우팅 그룹 내 채널 비율 설정에 따라 결제를 요청합니다.
이 외에 빌링키 발급 및 결제 요청 시 다른 기능들은 기존과 동일하게 사용이 가능합니다. 단, 결제대행사 별로 지원하는 기능이 다를 수 있으니 그룹 내에서 사용하는 모든 결제대행사에서 지원하는 기능만 사용하시길 권장드립니다.
빌링키 결제와 관련된 자세한 내용은 빌링결제 연동하기 문서를 참고하시기 바랍니다.
예제 코드
const issueResponse = await fetch("https://api.portone.io/billing-keys", {
method: "POST",
headers: {
Authorization: `PortOne ${PORTONE_API_SECRET}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
chanenlGroupId: "channel-group-live-94ab2b51-b7e1-4b74-9a9c-9fb6e117a6ac",
customer: {
id: "customerId_2333", // 고객사가 지정한 고객 식별정보를 입력해야 합니다.
name: {
full: "김포트", // 고객 이름을 입력해야 합니다.
},
phoneNumber: "01000001234", // 고객 전화번호를 입력해야 합니다.
email: "port@portone.io", // 고객 이메일을 입력해야 합니다.
},
method: {
card: {
credential: {
number: "0000123400001234", // 16자리 숫자만 입력해야 합니다.
expiryYear: "26", // 연도의 뒤 2자리를 입력해야 합니다.
expiryMonth: "12",
birthOrBusinessRegistrationNumber: "900101", // 생년월일 6자리 또는 사업자 등록번호 10자리를 입력해야 합니다.
passwordTwoDigits: "00", // 카드 비밀번호 앞 2자리 입력해야 합니다.
},
},
},
}),
});
if (!issueResponse.ok)
throw new Error(`issueResponse: ${await issueResponse.json()}`);
const {
billingKeyInfo: { billingKey, channels },
channelSpecificFailures,
} = await issueResponse.json();
// `channels` 필드에 사용 가능한 채널 여러 개가 포함된 것을 확인할 수 있습니다.
// 이 필드는 빌링키 조회에서도 확인 가능합니다.
console.log(`빌링키: ${billingKey}`);
console.log(`발급 성공한 채널: ${channels}`);
if (channelSpecificFailures.length !== 0)
console.log(`발급에 실패한 채널이 있습니다: ${channelSpecificFailures}`);
주요 파라미터
channelGroupId
* string
스마트 라우팅 그룹 ID
-
관리자 콘솔의 [연동 관리] → [스마트 라우팅] 메뉴에서 확인할 수 있습니다.
-
스마트 라우팅 그룹 ID를 지정하여 결제창을 호출하면, 스마트 라우팅 그룹 내 설정된 채널 비율에 따라 확률 기반으로 하나의 결제대행사가 호출됩니다.
필수 파라미터
-
paymentId
* string고객사 주문 고유 번호
-
customer
* object구매자 정보
-
id
* string구매자 식별정보
-
name
* object구매자 이름
-
full
* string구매자 전체 이름
full
파라미터 대신separated.first
와separated.last
파라미터로 사용해도 됩니다.
-
-
phoneNumber
* string구매자 연락처
가상계좌 발급 시 필수 입력해야 합니다.
-
email
* string구매자 이메일 주소
가상계좌 발급 시 필수 입력해야 합니다.
-
-
method
* object결제 수단
-
card
* object카드 결제
-
credential
* object카드 정보
-
number
* string카드 번호
-
expiryYear
* string카드 유효기간 중 연도
-
expiryMonth
* string카드 유효기간 중 월
-
birthOrBusinessRegistrationNumber
* string생년월일 또는 사업자번호
-
passwordTwoDigits
* string카드 비밀번호 앞 2자리
-
-
-