개발자센터
V1
V2
파트너 정산 릴리즈 노트 기술 블로그

스마트 라우팅 연동하기

스마트 라우팅 연동 방법을 안내합니다.

스마트 라우팅 기능이 궁금하다면 스마트 라우팅 기능 소개를 확인해 보세요!

스마트 라우팅을 이용하시려면 관리자콘솔에서 스마트 라우팅 그룹을 먼저 설정해야합니다. 그룹 설정 방법이 궁금하다면 스마트 라우팅 그룹 설정 가이드를 확인해 보세요.

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

      구매자 이메일 주소

기타 파라미터는 결제요청 파라미터 문서를 참고하시길 바립니다.

유의사항

스마트 라우팅 내 새로운 결제대행사 채널 추가 시 테스트 후 사용하시길 권장드립니다.

결제대행사별로 결제 수단에 따라 필수 파라미터가 다르므로 그룹 내 새로운 결제대행사 추가 시 테스트 환경에서 테스트를 진행한 후 실환경에 반영하시길 권장 드립니다. 필수 파라미터 조건을 충족하지 못하는 경우 에러가 리턴되며, 결제창이 정상적으로 호출되지 않을 수 있습니다.

간편결제 사용을 원하시는 경우 허브형으로 사용하시길 권장드립니다.

간편결제 허브형을 사용하시는 경우, 결제대행사 별 계약에 따라 결제창에 표시되는 간편결제가 상이할 수 있습니다.

간편결제 다이렉트 호출을 사용하시는 경우, 결제대행사 별 계약에 따라 결제 호출 시 에러가 리턴되며 결제창이 호출되지 않을 수 있습니다. 가급적 결제대행사 별 동일한 간편결제 수단을 모두 계약하신 후 사용하시길 권장드립니다.

단, 간편결제 직연동의 경우 스마트 라우팅 기능을 제공하지 않습니다.

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: {
          cardCredintial: {
            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.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의 channel 파라미터에서 확인 가능합니다.

수기(키인) 결제 시 카드를 이용하는 경우 결제대행사 계약을 사전에 확인하시길 바랍니다.

카드 결제의 경우 결제대행사에 따라 카드번호, 유효기간, 비밀번호, 생년월일 4가지 정보를 다르게 요구할 수 있습니다. 스마트 라우팅 사용 시 4개의 정보를 전부 입력하시거나 사용하시는 결제대행사의 계약 조건을 모두 충족할 수 있도록 파라미터를 입력한 후 결제 요청을 해야합니다.

가상계좌 발급 이용 시 고정식 가상계좌 사용을 권장하지 않습니다.

고정식 가상계좌의 경우 결제대행사별로 발급 유형이 다르므로 스마트 라우팅 이용 시 가상계좌 발급이 올바르지 않을 수 있습니다. 가상계좌 발급을 이용하시는 경우 일반(회전식) 가상계좌를 이용하시길 권장드립니다.

가상계좌 발급 이용 시 virtualAccount.expiry.validHours 사용을 권장하지 않습니다.

스마트 라우팅 이용 시 가상계좌 만료시간 파라미터 중 virtualAccount.expiry.validHours 사용을 권장하지 않습니다. 해당 파라미터의 경우 지원하는 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: {
        cardCredintial: {
          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.firstseparated.last 파라미터로 사용해도 됩니다.

    • phoneNumber * string

      구매자 연락처

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

    • email * string

      구매자 이메일 주소

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

  • method * object

    결제 수단

    • card * object

      카드 결제

      • credential * object

        카드 정보

        • number * string

          카드 번호

        • expiryYear * string

          카드 유효기간 중 연도

        • expiryMonth * string

          카드 유효기간 중 월

        • birthOrBusinessRegistrationNumber * string

          생년월일 또는 사업자번호

        • passwordTwoDigits * string

          카드 비밀번호 앞 2자리

유의사항

빌링키 발급 요청 시 지정한 그룹 내 모든 채널로 빌링키를 발급합니다.

그룹 내 채널을 활성화한 채로 비율을 0으로 설정한 경우 해당 채널로도 빌링키 발급을 요청합니다. 빌링키 발급을 원하지 않는 경우 채널을 비활성화 상태로 두거나 그룹 내에서 삭제해야 합니다.

슈퍼빌링키 발급 시 일부 PG사에 대해서만 발급될 수 있습니다.

슈퍼 빌링키를 발급 요청 시 일부 PG사는 요청은 성공하고, 일부 PG사는 요청은 실패하는 경우가 발생할 수 있습니다. 이 경우 포트원 빌링키(슈퍼빌링키)는 정상적으로 발급되지만 사용 가능한 빌링키는 요청이 성공한 결제대행사의 빌링키로 제한됩니다.

요청이 실패한 결제대행사 목록은 API 응답의 channelSpecificFailures 필드로 확인할 수 있고, 이 배열에 항목이 있는 경우 필요에 따라 빌링키 발급 실패로 취급하여 사용할 수 있습니다.

슈퍼빌링키 결제 시 특정 PG사를 지정할 수 있습니다.

슈퍼 빌링키를 이용해 결제를 요청할 때 결제 요청에 channelKey 파라미터를 전달하는 경우 해당 채널로 결제를 요청합니다.

슈퍼빌링키 결제 시 그룹 설정에 따라 결제됩니다.

channelKey를 별도로 전달하지 않은 경우 아래와 같이 자동으로 채널이 결정됩니다.

  • 슈퍼 빌링키 발급에 사용된 스마트 라우팅 그룹의 현재 설정된 채널 비율에 따라 확률에 기반하여 자동으로 선택합니다.

  • 만약 결제 시점에 스마트 라우팅 그룹 내에 새로운 결제대행사 채널이 추가되어 있는 경우, 해당 결제대행사의 빌링키가 발급되어 있지 않으므로 채널 선택 시 제외됩니다.

예를 들어 PG사 A, B, C에 대해 슈퍼 빌링키가 발급되었고, 이후 그룹 설정을 B 10%, C 30%, D 60%로 변경한 후 결제 요청을 하면 빌링키가 B와 C에 대해서만 존재하기 때문에 B와 C의 설정된 비율에 따라 확률에 기반하여 자동으로 선택됩니다.

슈퍼 빌링키를 이용하여 결제 요청 시 불가피하게 그룹 내 비율이 0인 채널로 진행될 수 있습니다.

슈퍼 빌링키를 이용하여 결제 요청했을 때, 슈퍼 빌링키에 맵핑된 결제대행사 빌링키 중 그룹 비율에 따라 사용 가능한 빌링키가 없는 경우 그룹 내 채널 비율이 0으로 설정되어있더라도 해당 결제대행사로 결제가 일어날 수 있습니다.

예를 들어, 그룹 내에 나이스페이먼츠, 이니시스, 토스페이먼츠 총 3개의 결제대행사를 설정한 경우 빌링키 발급 시 3개의 결제대행사로부터 빌링키를 발급 받은 후 슈퍼 빌링키에 맵핑 됩니다. 이후 그룹 설정을 토스페이먼츠 0%, 스마트로 100%로 변경한 경우 위에 발급한 슈퍼 빌링키로 결제 요청 시 토스페이먼츠 빌링키만 사용이 가능하기 때문에 0%로 결제 비율이 설정되어있음에도 토스페이먼츠로 결제가 발생하게 됩니다. 만약 기존에 발급한 결제대행사 채널이 모두 비활성화되어 있거나 그룹 내에서 삭제된 경우 결제가 실패되오니 그룹 설정 변경 시 유의하시기 바랍니다.