스마트 라우팅 기능이 궁금하다면 [스마트 라우팅 기능 소개](https://developers.portone.io/opi/ko/extra/smart-routing/intro)를 확인해 보세요!
스마트 라우팅을 이용하시려면 관리자콘솔에서 스마트 라우팅 그룹을 먼저 설정해야합니다.
그룹 설정 방법이 궁금하다면 [스마트 라우팅 그룹 설정 가이드](https://developers.portone.io/opi/ko/extra/smart-routing/console-guide)를 확인해 보세요.
## SDK(결제창) 인증결제 연동하기
SDK를 이용하는 경우 결제 호출 시 생성한 스마트 라우팅 그룹의 ID를 전용 파라미터인 `channelGroupId`에
지정하여 사용이 가능합니다.
이 외에 다른 결제 기능들은 기존과 동일하게 사용이 가능합니다. 단, 결제대행사 별로 지원하는 기능이 다를 수 있으니
그룹 내에서 사용하는 모든 결제대행사에서 지원하는 기능만 사용하시길 권장드립니다.
인증결제와 관련된 자세한 내용은 [인증 결제 연동하기](https://developers.portone.io/opi/ko/integration/start/v1/auth) 문서를 참고하시기 바랍니다.
### 예제 코드
```ts
IMP.request_pay(
{
// 결제대행사를 지정할 때 사용한 channelKey, pg 대신
// channelGroupId 파라미터에 스마트 라우팅 그룹 ID를 설정합니다.
channelGroupId: "channel-group-live-f042e8e2-92f1-4f68-ad61-cec6ede41529",
pay_method: "card", //결제수단 선택
merchant_uid: "ORD20180131-0000011", //고객사 주문번호
name: "Norway swivel chair", //주문명
amount: 1000, // 결제 금액
//고객 정보
buyer_email: "gildong@gmail.com",
buyer_name: "Hong Gildong",
buyer_tel: "010-4242-4242",
buyer_addr: "Shinsa-dong, Gangnam-gu, Seoul",
buyer_postcode: "01181",
},
function (rsp) {
// callback
if (rsp.success) {
// Payment is successful
} else {
// Payment failed
}
},
);
```
인증결제와 관련된 자세한 내용은 [인증 결제 연동하기](https://developers.portone.io/opi/ko/integration/start/v2/checkout) 문서를 참고하시기 바랍니다.
### 예제 코드
```tsx
//포트원 인증결제 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를 지정하여 결제창을 호출하면, 스마트 라우팅 그룹 내 설정된 채널 비율에 따라
확률 기반으로 하나의 결제대행사가 호출됩니다.
### 필수 파라미터
각 파라미터에 대한 상세한 설명은 [결제요청 파라미터](https://developers.portone.io/sdk/ko/v1-sdk/javascript-sdk/payrq) 문서를 참고하시기 바랍니다.
- merchant\_uid: string
**고객사 주문번호**
- name: string
**주문명**
- amount: number
**결제금액**
- pay\_method: string
**결제수단 구분코드**
- custom\_data: object
**사용자 정의 데이터**
결제 응답시 **echo** 로 받아보실 수 있는 필드 입니다.
JSON notation(string)으로 저장됩니다.
주문 건에 대해 부가정보를 저장할 공간이 필요할 때 사용합니다
- tax\_free: number
**면세금액**
결제금액 중 면세금액에 해당하는 금액을 입력합니다.
- vat\_amount: number
**부가세**
결제금액 중 부가세에 해당하는 금액을 입력합니다. (기본값: null)
- vbank\_due: string
**가상계좌 입금기한**
스마트 라우팅을 이용한 가상계좌 결제 사용 시 필수 입력해야 합니다.
다음과 같은 형식으로 설정이 가능합니다 :
`YYYY-MM-DD`
`YYYYMMDD`
`YYYY-MM-DD HH:mm:ss`
`YYYYMMDDHHmmss`
- buyer\_tel: string
**주문자 연락처**
일부 PG사에서 해당 필드 누락시 오류 발생
- buyer\_email: string
**주문자 이메일**
일부 PG사에서 해당 필드 누락시 오류 발생(페이먼트월)
기타 파라미터는 [결제요청 파라미터](https://developers.portone.io/sdk/ko/v1-sdk/javascript-sdk/payrq) 문서를 참고하시길 바랍니다.
각 파라미터에 대한 상세한 설명은 [결제요청 파라미터](https://developers.portone.io/sdk/ko/v2-sdk/payment-request) 문서를 참고하시기 바랍니다.
- 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
**구매자 이메일 주소**
기타 파라미터는 \[결제요청 파라미터]\(/sdk/ko/v2-sdk/payment-request 문서를 참고하시길 바립니다.
### 유의사항
```ts
// 포트원 수기(키인)결제 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()}`);
```
```ts
// 포트원 수기(키인)결제 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()}`);
```
### 주요 파라미터
- channelGroupId: string
**스마트 라우팅 그룹 ID**
관리자 콘솔의 \[연동 관리] → \[스마트 라우팅] 메뉴에서 확인할 수 있습니다.
스마트 라우팅 그룹 ID를 지정하여 결제창을 호출하면, 스마트 라우팅 그룹 내 설정된 채널 비율에 따라
확률 기반으로 하나의 결제대행사가 호출됩니다.
### 필수 파라미터
- merchant\_uid: string
**고객사 거래 고유번호**
- amount: number
**주문 금액**
- card\_number: string
**카드번호**
(dddd-dddd-dddd-dddd) 기재 양식을 유의하세요.
- expiry: string
**카드 유효기간**
(YYYY-MM) 기재 양식을 유의하세요.
- 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사 결제 요청시에는 별도로 검증하지 않습니다.
### 유의사항
```ts
const issueResponse = await fetch(
`https://api.iamport.kr/subscribe/customers/${customer_uid}`,
{
method: "POST",
headers: {
Authorization: `Bearer ${ACCESS_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
channelGroupId: "channel-group-live-f042e8e2-92f1-4f68-ad61-cec6ede41529",
customer_id: customer_id, //고객 식별 정보로 고객사에서 기입
card_number: "YYYY-YYYY-YYYY-YYYY", // 카드 번호 16자리
expiry: "YYYY-MM", // 카드 유효기간
birth: "YYMMDD", // 생년 월일. 무기명 법인카드의 경우 사업자 번호 10자리 입력
pwd_2digit: "NN", //카드 비밀번호 앞 2자리
// 중략...
}),
},
);
if (!issueResponse.ok)
throw new Error(`issueResponse: ${await issueResponse.json()}`);
const {
billingKeyInfo: { customer_uid },
} = await issueResponse.json();
// 빌링키가 발급되었습니다! 빌링키를 저장하거나 결제하는 로직을 구성하세요.
```
```ts
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}`);
```
```ts
// 포트원 빌링키 결제 API 호출
const paymentResponse = await fetch(
"https://api.iamport.kr/subscribe/payments/again",
{
method: "POST",
headers: {
Authorization: `Bearer ${ACCESS_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
customer_uid: "customer_uid", // 슈퍼 빌링키
merchant_uid: "merchant_uid",
name: "월간 이용권 정기결제",
// 빌링키 결제 API를 참고해 고객 정보를 채워주세요.
amount: {
total: 8900,
},
currency: "KRW",
}),
},
);
if (!paymentResponse.ok)
throw new Error(`paymentResponse: ${await paymentResponse.json()}`);
```
```ts
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()}`);
```
```ts title="server-side"
// 결제 예약
const paymentResponse = await fetch(
"https://api.iamport.kr/subscribe/payments/schedule",
{
method: "POST",
headers: {
Authorization: `Bearer ${ACCESS_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
customer_uid: "gildong_0001_1234", // 슈퍼 빌링키
schedules: [
{
merchant_uid: "order_monthly_0001", // 주문 번호
schedule_at: 1519862400, // 결제 시도 시각 in Unix Time Stamp. 예: 다음 달 1일
amount: 8900,
name: "월간 이용권 정기결제",
buyer_name: "홍길동",
buyer_tel: "01012345678",
buyer_email: "gildong@gmail.com",
// 중략...
},
],
}),
},
);
```
```ts
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()}`);
```
### 주요 파라미터
- channelGroupId: string
**스마트 라우팅 그룹 ID**
관리자 콘솔의 \[연동 관리] → \[스마트 라우팅] 메뉴에서 확인할 수 있습니다.
스마트 라우팅 그룹 ID를 지정하여 결제창을 호출하면, 스마트 라우팅 그룹 내 설정된 채널 비율에 따라
확률 기반으로 하나의 결제대행사가 호출됩니다.
스마트 라우팅 그룹 ID를 지정하여 빌링키 발급 API를 호출하면, 스마트 라우팅 그룹 내 활성화 된 채널들에 대해 빌링키 발급을 시도합니다.
### 필수 파라미터