스마트 라우팅 - 연동하기
멀티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",
},
});
주요 파라미터
스마트 라우팅 그룹 ID
관리자 콘솔의 [연동 관리] → [스마트 라우팅] 메뉴에서 확인할 수 있습니다.
스마트 라우팅 그룹 ID를 지정하여 결제창을 호출하면, 스마트 라우팅 그룹 내 설정된 채널 비율에 따라 확률 기반으로 하나의 결제대행사가 호출됩니다.
필수 파라미터
각 파라미터에 대한 상세한 설명은 결제요청 파라미터 문서를 참고하시기 바랍니다.
고객사 ID
고객사 주문 고유 번호
주문명
결제 금액
결제 통화
결제수단 구분코드
가상계좌 결제 사용 시 필요한 파라미터입니다.
가상계좌 입금 만료기한
스마트 라우팅을 이용한 가상계좌 결제 사용 시 필수 입력해야 합니다.
가상계좌 입금 유효 시간
가상계좌 입금 유효 시각
간편결제 정보
스마트 라우팅을 이용한 간편결제 다이렉트 호출 시 필수 입력해야 합니다.
간편결제 수단
상품 유형
스마트 라우팅을 이용한 휴대폰 소액결제 사용 시 필수 입력해야 합니다.
구매자 정보
구매자 전체 이름
fullName
파라미터 대신 firstName
과 lastName
파라미터를 사용해도 됩니다.
구매자 연락처
구매자 이메일 주소
기타 파라미터는 [결제요청 파라미터](/sdk/ko/v2-sdk/payment-request 문서를 참고하시길 바립니다.
유의사항
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()}`);
// 포트원 수기(키인)결제 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: "channel-group-live-94ab2b51-b7e1-4b74-9a9c-9fb6e117a6ac",
orderName: "월간 이용권 정기결제",
// 수기 결제 API를 참고해 고객 정보를 채워주세요.
customer: {
name: {
full: "김포트", // 고객 이름을 입력해야 합니다.
},
phoneNumber: "01000001234", // 고객 전화번호를 입력해야 합니다.
email: "port@portone.io", // 고객 이메일을 입력해야 합니다.
},
amount: {
total: 8900,
},
currency: "KRW",
// 수기(키인)결제 API를 참고해 카드 / 가상계좌 정보를 채워주세요.
method: {
virtaulAccount: {
bank: "KOOKMIN", // 은행별 enum 확인 후 발급할 은행 값을 입력해야 합니다.
expiry: {
dueDate: "2023-12-21T00:00:00+09:00", // RFC 3339 형식으로 입력해야 합니다.
},
option: {
type: "NORMAL", // 일반 가상계좌 (회전식)인 경우 `NORMAL`로 입력해야 합니다.
},
cashReceipt: {
type: "PERSONAL", // 소득공제용인 경우 `PERSONAL`, 지출증빙용인 경우 `CORPORATE`로 입력해야 합니다.
customerIdentityNumber: "01000001234", // 현금영수증 발급 번호
},
remitteeName: "포트원", // 가상계좌 예금주명을 입력해야 합니다.
},
productCount: 1, // 상품 개수를 입력해야 합니다.
},
}),
},
);
if (!paymentResponse.ok)
throw new Error(`paymentResponse: ${await paymentResponse.json()}`);
주요 파라미터
스마트 라우팅 그룹 ID
관리자 콘솔의 [연동 관리] → [스마트 라우팅] 메뉴에서 확인할 수 있습니다.
스마트 라우팅 그룹 ID를 지정하여 결제창을 호출하면, 스마트 라우팅 그룹 내 설정된 채널 비율에 따라 확률 기반으로 하나의 결제대행사가 호출됩니다.
필수 파라미터
고객사 주문 고유 번호
주문명
주문 금액
결제 금액
결제 통화
구매자 정보
구매자 이름
구매자 전체 이름
full
파라미터 대신 separated.first
와 separated.last
파라미터로 사용해도 됩니다.
구매자 연락처
가상계좌 발급 시 필수 입력해야 합니다.
구매자 이메일 주소
가상계좌 발급 시 필수 입력해야 합니다.
결제 수단
카드 결제
카드 정보
카드 번호
카드 유효기간 중 연도
카드 유효기간 중 월
생년월일 또는 사업자번호
카드 비밀번호 앞 2자리
가상 계좌
은행 정보
만료 기한
만료 시점
가상계좌 발급 방식
가상계좌 발급 유형
일반 가상계좌 (회전식)인 경우 NOMAL
를 입력해야 합니다.
현금영수증 정보
현금영수증 발급 유형
현금영수증 발급 식별 정보
가상계좌 예금주명
상품 유형
KSNET로 카드 결제시에만 MID 설정 정보와 검증을 진행합니다. 다른 PG사 결제 요청시에는 별도로 검증하지 않습니다.
상품 개수
스마트로로 가상계좌 발급시에만 정보가 유효합니다. 다른 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}`);
const issueResponse = await fetch(
`https://api.portone.io/payments/${encodeURIComponent(UNIQUE_PAYMENT_ID)}/billing-key`,
{
method: "POST",
headers: {
Authorization: `PortOne ${PORTONE_API_SECRET}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
billingKey: "billing-key-018fa367-cdd9-d8fd-2256-c43ce0e475d6", // 발급된 빌링키 값을 입력해야 합니다.
orderName: "후불 결제",
customer: {
id: "customerId_2333", // 고객사가 지정한 고객 식별정보를 입력해야 합니다.
name: {
full: "김포트", // 고객 이름을 입력해야 합니다.
},
phoneNumber: "01000001234", // 고객 전화번호를 입력해야 합니다.
email: "port@portone.io", // 고객 이메일을 입력해야 합니다.
},
amount: {
total: 8900,
},
currency: "KRW",
productType: "PHYSICAL", // 상품이 실물인 경우 `PHYSICAL`, 디지털인 경우 `DIGITAL` 입력해야 합니다.
productCount: 1, // 상품 개수를 입력해야 합니다.
}),
},
);
if (!issueResponse.ok)
throw new Error(`issueResponse: ${await issueResponse.json()}`);
const issueResponse = await fetch(
`https://api.portone.io/payments/${encodeURIComponent(UNIQUE_PAYMENT_ID)}/schedule`,
{
method: "POST",
headers: {
Authorization: `PortOne ${PORTONE_API_SECRET}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
payment: {
billingKey: "billing-key-018fa367-cdd9-d8fd-2256-c43ce0e475d6", // 발급된 빌링키 값을 입력해야 합니다.
orderName: "월간 이용권 정기 결제",
customer: {
id: "customerId_2333", // 고객사가 지정한 고객 식별정보를 입력해야 합니다.
name: {
full: "김포트", // 고객 이름을 입력해야 합니다.
},
phoneNumber: "01000001234", // 고객 전화번호를 입력해야 합니다.
email: "port@portone.io", // 고객 이메일을 입력해야 합니다.
},
amount: {
total: 8900,
},
currency: "KRW",
productType: "PHYSICAL", // 상품이 실물인 경우 `PHYSICAL`, 디지털인 경우 `DIGITAL` 입력해야 합니다.
productCount: 1, // 상품 개수를 입력해야 합니다.
},
timeToPay: "2024-05-01T00:00:00+09:00", // ISO8601 형식으로 입력해야 합니다.
}),
},
);
if (!issueResponse.ok)
throw new Error(`issueResponse: ${await issueResponse.json()}`);
주요 파라미터
스마트 라우팅 그룹 ID
관리자 콘솔의 [연동 관리] → [스마트 라우팅] 메뉴에서 확인할 수 있습니다.
스마트 라우팅 그룹 ID를 지정하여 결제창을 호출하면, 스마트 라우팅 그룹 내 설정된 채널 비율에 따라 확률 기반으로 하나의 결제대행사가 호출됩니다.
필수 파라미터
고객사 주문 고유 번호
구매자 정보
구매자 이름
구매자 전체 이름
full
파라미터 대신 separated.first
와 separated.last
파라미터로 사용해도 됩니다.
구매자 연락처
가상계좌 발급 시 필수 입력해야 합니다.
구매자 이메일 주소
가상계좌 발급 시 필수 입력해야 합니다.
결제 수단
카드 결제
카드 정보
카드 번호
카드 유효기간 중 연도
카드 유효기간 중 월
생년월일 또는 사업자번호
카드 비밀번호 앞 2자리
고객사 주문 고유 번호
주문명
주문 금액
결제 금액
결제 통화
구매자 정보
구매자 식별정보
구매자 이름
구매자 전체 이름
full
파라미터 대신 separated.first
와 separated.last
파라미터로 사용해도 됩니다.
구매자 연락처
가상계좌 발급 시 필수 입력해야 합니다.
구매자 이메일 주소
가상계좌 발급 시 필수 입력해야 합니다.
상품 유형
KSNET로 카드 결제시에만 MID 설정 정보와 검증을 진행합니다. 다른 PG사 결제 요청시에는 별도로 검증하지 않습니다.
상품 개수
스마트로로 가상계좌 발급시에만 정보가 유효합니다. 다른 PG사 결제 요청시에는 별도로 검증하지 않습니다.
고객사 주문 고유 번호
결제 정보
빌링키
주문명
주문 금액
결제 금액
결제 통화
구매자 정보
구매자 이름
구매자 전체 이름
full
파라미터 대신 separated.first
와 separated.last
파라미터로 사용해도 됩니다.
구매자 연락처
가상계좌 발급 시 필수 입력해야 합니다.
구매자 이메일 주소
가상계좌 발급 시 필수 입력해야 합니다.
상품 유형
KSNET로 카드 결제시에만 MID 설정 정보와 검증을 진행합니다. 다른 PG사 결제 요청시에는 별도로 검증하지 않습니다.
상품 개수
스마트로로 가상계좌 발급시에만 정보가 유효합니다. 다른 PG사 결제 요청시에는 별도로 검증하지 않습니다.
결제 예정 시점