스마트 라우팅 - 연동하기

멀티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

      구매자 이메일 주소

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

유의사항

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.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}`);

주요 파라미터

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자리

유의사항