스마트 라우팅 - 연동하기

멀티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 파라미터 대신 firstNamelastName 파라미터를 사용해도 됩니다.

phoneNumber: string

구매자 연락처

email: string

구매자 이메일 주소

기타 파라미터는 [결제요청 파라미터](/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()}`);

주요 파라미터

channelGroupId: string

스마트 라우팅 그룹 ID

관리자 콘솔의 [연동 관리] → [스마트 라우팅] 메뉴에서 확인할 수 있습니다.

스마트 라우팅 그룹 ID를 지정하여 결제창을 호출하면, 스마트 라우팅 그룹 내 설정된 채널 비율에 따라 확률 기반으로 하나의 결제대행사가 호출됩니다.

필수 파라미터

paymentId: string

고객사 주문 고유 번호

orderName: string

주문명

amount: object

주문 금액

total: number

결제 금액

currency: string

결제 통화

customer: object

구매자 정보

name: object

구매자 이름

full: string

구매자 전체 이름

full 파라미터 대신 separated.firstseparated.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}`);
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()}`);

주요 파라미터

channelGroupId: string

스마트 라우팅 그룹 ID

관리자 콘솔의 [연동 관리] → [스마트 라우팅] 메뉴에서 확인할 수 있습니다.

스마트 라우팅 그룹 ID를 지정하여 결제창을 호출하면, 스마트 라우팅 그룹 내 설정된 채널 비율에 따라 확률 기반으로 하나의 결제대행사가 호출됩니다.

필수 파라미터

paymentId: string

고객사 주문 고유 번호

customer: object

구매자 정보

name: object

구매자 이름

full: string

구매자 전체 이름

full 파라미터 대신 separated.firstseparated.last 파라미터로 사용해도 됩니다.

phoneNumber: string

구매자 연락처

가상계좌 발급 시 필수 입력해야 합니다.

email: string

구매자 이메일 주소

가상계좌 발급 시 필수 입력해야 합니다.

method: object

결제 수단

card: object

카드 결제

credential: object

카드 정보

number: string

카드 번호

expiryYear: string

카드 유효기간 중 연도

expiryMonth: string

카드 유효기간 중 월

birthOrBusinessRegistrationNumber: string

생년월일 또는 사업자번호

passwordTwoDigits: string

카드 비밀번호 앞 2자리

paymentId: string

고객사 주문 고유 번호

orderName: string

주문명

amount: object

주문 금액

total: number

결제 금액

currency: string

결제 통화

customer: object

구매자 정보

id: string

구매자 식별정보

name: object

구매자 이름

full: string

구매자 전체 이름

full 파라미터 대신 separated.firstseparated.last 파라미터로 사용해도 됩니다.

phoneNumber: string

구매자 연락처

가상계좌 발급 시 필수 입력해야 합니다.

email: string

구매자 이메일 주소

가상계좌 발급 시 필수 입력해야 합니다.

productType: string

상품 유형

KSNET로 카드 결제시에만 MID 설정 정보와 검증을 진행합니다. 다른 PG사 결제 요청시에는 별도로 검증하지 않습니다.

productCount: string

상품 개수

스마트로로 가상계좌 발급시에만 정보가 유효합니다. 다른 PG사 결제 요청시에는 별도로 검증하지 않습니다.

paymentId: string

고객사 주문 고유 번호

payment: object

결제 정보

billingKey: string

빌링키

orderName: string

주문명

amount: object

주문 금액

total: number

결제 금액

currency: string

결제 통화

customer: object

구매자 정보

name: object

구매자 이름

full: string

구매자 전체 이름

full 파라미터 대신 separated.firstseparated.last 파라미터로 사용해도 됩니다.

phoneNumber: string

구매자 연락처

가상계좌 발급 시 필수 입력해야 합니다.

email: string

구매자 이메일 주소

가상계좌 발급 시 필수 입력해야 합니다.

productType: string

상품 유형

KSNET로 카드 결제시에만 MID 설정 정보와 검증을 진행합니다. 다른 PG사 결제 요청시에는 별도로 검증하지 않습니다.

productCount: string

상품 개수

스마트로로 가상계좌 발급시에만 정보가 유효합니다. 다른 PG사 결제 요청시에는 별도로 검증하지 않습니다.

timeToPay: string

결제 예정 시점

유의사항