개발자센터

스마트로

스마트로 결제 연동 방법을 안내합니다.

채널 설정하기

  • 결제대행사 채널 설정하기 페이지의 내용을 참고하여 채널 설정을 진행합니다. V2 결제 모듈을 사용하시려면 스마트로(신모듈)로 연동하셔야 합니다.

가능한 결제 수단

  • 결제창 일반결제

    payMethod 파라미터를 결제수단에 따라 아래와 같이 설정해야 합니다.

    • 신용카드 : CARD
    • 실시간 계좌이체 : TRANSFER
    • 가상계좌 : VIRTUAL_ACCOUNT
    • 휴대폰 소액결제 : MOBILE
    • 간편 결제 : EASY_PAY

  • 결제창 빌링키발급

    payMethod 파라미터를 card로 설정해야 합니다

  • API 수기(키인) 결제

    method 파라미터를 virtualAccount로 설정해야 합니다.

  • API 빌링키 발급

    method 파라미터를 card로 설정해야 합니다.

공통 유의사항

SDK 결제 요청하기

결제 요청 시에는 requestPayment 함수를 호출해야 합니다. channelKey파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 스마트로 채널 사용을 명시해주세요.

스마트로 기준으로 작성한 예시 코드는 아래와 같습니다.

import * as PortOne from "@portone/browser-sdk/v2";
function requestPayment() {
  PortOne.requestPayment({
    storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요.
    paymentId: `payment${crypto.randomUUID()}`,
    orderName: "나이키 와플 트레이너 2 SD",
    totalAmount: 1000,
    currency: "CURRENCY_KRW",
    channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
    payMethod: "CARD",
    customer: {
      phoneNumber: "010-0000-1234",
    },
  });
}

주요 파라미터

storeId: string

스토어 아이디

포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다.

paymentId: string

고객사 주문 고유 번호

고객사에서 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다. 이미 승인 완료된 paymentId로 결제를 시도하는 경우 에러가 발생합니다.

orderName: string

주문명

주문명으로 고객사에서 자유롭게 입력합니다.

channelKey: string

채널 키

포트원 콘솔 내 [결제연동] > [채널관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다.

totalAmount: number

결제 금액

결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다.

currency: string

결제 통화

결제통화로 원화 결제 시 KRW로 입력해야 합니다.

payMethod: string

결제수단 구분코드

결제 호출 시 결제수단을 지정할 때 사용됩니다.

  • 신용카드 : CARD
  • 실시간 계좌이체 : TRANSFER
  • 가상계좌 : VIRTUAL_ACCOUNT
  • 휴대폰 소액결제 : MOBILE
  • 간편 결제 : EASY_PAY
customer?: object

고객 정보

customerId?: string

구매자 고유 ID

  • 스마트로의 경우 간편결제로 결제 요청시 필수로 입력해야 합니다.
  • 20자 이하로만 입력 가능합니다.
phoneNumber?: string

구매자 연락처

  • 스마트로의 경우 결제창 호출 시 필수로 입력합니다.
bypass?: oneof object

PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음

smartro_v2?: object

스마트로에서 제공하는 파라미터 모음

GoodsCnt?: number

결제 상품 품목 갯수

SkinColor?: string

UI 색상 스타일

  • 미 설정시 기본으로 RED로 적용됩니다.
  • RED, GREEN, BLUE, PURPLE를 선택할 수 있습니다.
OpenType?: string

해외 카드 사용 설정

  • 국내 카드: KR, 해외 카드: EN
  • 미 설정시 기본으로 KR로 적용됩니다.
  • EN으로 설정 시 해외 카드만 결제가 가능합니다.

  • 예시 코드

    {
  "bypass": {
    "smartro_v2": {
      "GoodsCnt": 2,
      "SkinColor": "BLUE",
      "OpenType": "EN"
    }
  }
}

SDK 빌링키 발급 요청하기

빌링키 발급 요청 시에는 requestBillingKeyIssue 함수를 호출해야 합니다. channelKey파라미터에 결제 채널 연동 후 생성된 채널 키값을 지정하여 스마트로 채널 사용을 명시해주세요.

스마트로 기준으로 작성한 예시 코드는 아래와 같습니다.

import * as PortOne from "@portone/browser-sdk/v2";
function requestIssueBillingKey() {
  PortOne.requestIssueBillingKey({
    storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요.
    channelKey: "channel-key-3b37819a-1c72-4deb-a245-8c810af5403d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
    billingKeyMethod: "CARD",
  });
}

주요 파라미터

storeId: string

스토어 아이디

포트원 계정에 생성된 상점을 식별하는 고유한 값으로 관리자 콘솔에서 확인할 수 있습니다.

channelKey: string

채널 키

포트원 콘솔 내 [결제연동] > [채널관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다.

billingKeyMethod: string

빌링키 발급수단

스마트로는 카드 이외 발급 수단은 지원하지 않아 CARD로 설정해야 합니다.

issueId: string

빌링키 발급 건 고유 ID

  • 고객사에서 채번하여 사용해야 합니다.
  • 스마트로의 경우 필수 입력해야 하며, 특수문자는 사용이 불가합니다.
customer?: object

고객 정보

customerId?: string

구매자 고유 ID

  • 스마트로의 경우 빌링키 발급 시 필수로 입력해야 합니다.
  • 20자 이하로만 입력 가능합니다.
bypass?: oneof object

PG사 결제창 호출 시 PG사로 그대로 bypass할 파라미터들의 모음

smartro_v2?: object

스마트로에서 제공하는 파라미터 모음

SkinColor?: string

UI 색상 스타일

  • 미 설정시 기본으로 RED로 적용됩니다.
  • RED, GREEN, BLUE, PURPLE를 선택할 수 있습니다.
IsPwdPass?: string

결제 비밀번호 등록 Skip 여부

  • 비밀번호 설정 미사용: Y, 비밀번호 설정 사용: N
  • 미 설정시 기본으로 N으로 적용됩니다.

SDK 연동 유의사항

사전 계약

아래 기능을 사용하시려면 스마트로에 사전 신청 후 계약이 완료되어야 합니다. 그렇지 않은 상태에서 해당 기능 이용시 결제 승인에 실패하거나, 승인에 성공하더라도 의도한 바와는 다른 응답( ex. 결제창에서 에스크로 결제를 했으나 비-에스크로 결제 응답을 받음)을 얻게 될 수 있으니 주의해주시기 바랍니다.

  • 간편결제 사용
  • 면세 / 복합과세 사용
  • 할부 사용
  • 상점 부담 무이자 할부 사용
  • 카드사 포인트 사용
  • 에스크로 사용
  • [TBD] 해외 결제 사용

카드 결제

간편 결제

가상계좌 결제

휴대폰 소액결제

빌링키 발급

에스크로 결제

기타

SDK 결제 FAQ

API 수기(키인)결제 요청하기

수기(키인)로 결제하기 위해서는 POST /payments/${PAYMENT_ID_HERE}/instant를 이용하여 결제 요청을 해야합니다. 스마트로의 경우 결제수단은 가상계좌 발급만 가능하며, 예시코드는 아래와 같습니다.

// ... 수기(키인) 결제
const issueResponse = await axios({
  url: `https://api.portone.io/payments/${PAYMENT_ID_HERE}/instant`,
  method: "post",
  headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
  data: {
    channelKey: "channel-key-9987cb87-****-****-****-********896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
    orderName: "나이키 와플 트레이너 2 SD",
    amount: {
      total: 10000,
    },
    currency: "KRW",
    customer: {
      name: {
        full: "홍길동",
      },
      email: "test@test.com",
      phoneNumber: "010-1234-0000",
    },
    method: {
      virtualAccount: {
        bank: `SHINHAN`,
        expiry: {
          dueDate: `2024-11-12T00:00:00+09+00`, //입금기한은 미래시간만 가능합니다.
        },
        option: `NOMAL`,
        cashReceipt: {
          type: `PERSONAL`,
          customerIdentityNumber: `010-1234-0000`,
        },
        remitteeName: `테스트`,
      },
    },
    productCount: 1,
  },
});

주요 파라미터

paymentId: string

고객사 주문 고유 번호

고객사에서 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다. 이미 승인 완료된 paymentId로 결제를 시도하는 경우 에러가 발생합니다.

orderName: string

주문명

주문명으로 고객사에서 자유롭게 입력합니다.

channelKey: string

채널 키

포트원 콘솔 내 [결제연동] > [채널관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다.

amount: object

결제 금액

total: number

총 결제 금액

결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다.

currency: string

결제 통화

결제통화로 원화 결제 시 KRW로 입력해야 합니다.

method: object

결제수단 정보

스마트로의 경우 가상계좌만 지원합니다.

virtualAccount: object

가상계좌 결제 시 파라미터

bank: string

발급 은행

expiry: object

입금 만료 기한

validHours?: integer

유효 시간

dueDate?: string

만료 시점

시간은 ISO8601 형식으로 입력해야 합니다.

option: object

가상계좌 발급 방식

type: string

가상계좌 발급 유형

발급 유형은 ENUM으로 정의되어 있습니다.

  • 회전식 가상계좌 : NORMAL
  • 고정식 가상계좌 : FIXED
  • 회전식 가상계좌는 일반적으로 사용되는 방식이며 PG사에서 직접 채번한 가상계좌번호를 사용합니다.
fixed?: object

고정식 가상계좌 발급 유형

pgAccountId?: string

고정식 가상계좌 ID

  • 고객사가 가상계좌번호를 직접 관리하지 않고 PG사가 pgAccountId에 매핑되는 가상계좌번호를 내려주는 방식입니다. 동일한 pgAccountId로 가상계좌 발급 요청시에는 항상 같은 가상계좌번호가 내려옵니다.

  • 스마트로의 경우 해당 방식만 지원합니다.

cashReceipt?: object

현금영수증 정보

type?: string

발급 유형

발급 유형은 ENUM으로 정의되어 있습니다.

  • 소득공제용 : PERSONAL
  • 지출증빙용 : CORPORATE
  • 미발행 : NO_RECEIPT
customerIdentityNumber?: string

현금영수증 식별 번호

  • 소득공제인 경우 주민등록번호 혹은 휴대폰 번호를 입력해야 합니다.
  • 지출증빈인 경우 사업자등록번호를 입력해야 합니다.
remitteeName?: string

예금주명

customer?: object

고객 정보

name?: object

고객 이름

full?: string

한 줄 이름 형식 (ex. 김포트)

separated?: object

분리된 이름

first?: string

이름

last?: string

성

phoneNumber?: string

구매자 연락처

email?: string

구매자 이메일

productCount?: integer

상품 개수

API 빌링키 발급

빌링키를 발급하기 위해서는 POST /billing-keys를 이용하여 빌링키 발급 요청을 해야합니다.

예시코드

const issueResponse = await axios({
  url: "https://api.portone.io/billing-keys",
  method: "post",
  headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
  data: {
    channelKey: "channel-key-9987cb87-****-****-****-********896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
    customer: {
      id: "customer-1234", // 고객사에서 관리하는 고객 고유번호
    },
    method: {
      card: {
        credential: {
          number: "1111111111111111",
          expiryMonth: "01",
          expiryYear: "20",
          birthOrBusinessRegistrationNumber: "900101",
          passwordTwoDigits: "00",
        },
      },
    },
  },
});

빌링키 발급 주요 파라미터

channelKey: string

채널 키

포트원 콘솔 내 [결제연동] > [채널관리] 화면에서 채널 추가 시 생성되는 값입니다. 결제 호출 시 채널을 지정할 때 사용됩니다.

method: object

결제수단 정보

스마트로의 경우 가상계좌만 지원합니다.

card?: object

카드 결제 시 파라미터

credential?: object

인증 관련 정보

number?: string

카드 번호

expiryYear?: string

유효 기간 만료 연도 (YY 형식 ex. 24)

expiryMonth?: string

유효기간 만료 월 (MM 형식 ex. 05)

birthOrBusinessRegistrationNumber: string

생년월일 또는 사업자 등록 번호

passwordTwoDigits: string

비밀번호 앞 두자리

customer?: object

고객 정보

customerId?: string

구매자 고유 ID

  • 스마트로의 경우 빌링키 발급 시 필수로 입력해야 합니다.
  • 20자 이하로만 입력 가능합니다.

API 빌링키 단건 결제 요청하기

발급된 빌링키로 단건 결제를 하기 위해 POST /payments/${PAYMENT_ID_HERE}/billing-key를 이용하여 결제를 요청합니다.

예시코드

const response = await axios({
  url: `https://api.portone.io/payments/${PAYMENT_ID_HERE}/billing-key`,
  method: "post",
  headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
  data: {
    billingKey: "billing-key-1", // 빌링키 발급 API를 통해 발급받은 빌링키
    orderName: "월간 이용권 정기결제",
    customer: {
      id: "customer-1234", // 고객사에서 관리하는 고객 고유번호
      phoneNumber: `010-1234-5678`,
      email: `test@test.com`,
    },
    amount: {
      total: 10000,
    },
    currency: "KRW",
    productCount: 1,
  },
});

빌링키 단건 결제 주요 파라미터

paymentId: string

결제 주문 번호

  • 고객사에서 채번하여 사용하는 주문번호로 고유한 값이여야 합니다.
  • URL path에 포함하여 요청해야 합니다.
billingKey: string

빌링키 결제에 사용할 빌링키

orderName: string

주문명

amount: object

결제 금액

total: number

총 결제 금액

결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다.

currency: string

결제 통화

결제통화로 원화 결제 시 KRW로 입력해야 합니다.

customer?: object

고객 정보

name: object

고객 이름

full?: string

한 줄 이름 형식 (ex. 김포트)

separated?: object

분리된 이름

first?: string

이름

last?: string

성

phoneNumber: string

구매자 연락처

email: string

구매자 이메일

productCount?: integer

상품 개수

API 빌링키 예약/반복 결제

예약 결제를 하기위해서는 POST /payments/${PAYMENT_ID_HERE}/schedule 를 이용하여 결제를 예약합니다.

예시코드

const response = await axios({
  url: `https://api.portone.io/payments/${PAYMENT_ID_HERE}/schedule`,
  method: "post",
  headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
  data: {
    payment: {
      billingKey: "billing-key-1", // 빌링키 발급 API를 통해 발급받은 빌링키
      orderName: "월간 이용권 정기결제",
      customer: {
        id: "customer-1234", // 고객사에서 관리하는 고객 고유번호
      },
      amount: {
        total: 10000,
      },
      currency: "KRW",
    },
    timeToPay: "2023-01-01 00:00:00", // 결제를 시도할 시각
  },
});

빌링키 예약 결제 주요 파라미터

paymentId: string

결제 주문 번호

  • 고객사에서 채번하여 사용하는 주문번호로 고유한 값이여야 합니다.
  • URL path에 포함하여 요청해야 합니다.
payment: object

빌링키 결제 요청 입력정보

billingKey: string

빌링키 결제에 사용할 빌링키

orderName: string

주문명

amount: object

결제 금액

total: number

총 결제 금액

결제 금액으로 결제를 원하는 통화(currency)별 scale factor(소수점 몇번째 자리까지 유효한지)를 고려한 number 형식만 허용됩니다.

currency: string

결제 통화

결제통화로 원화 결제 시 KRW로 입력해야 합니다.

timeToPay: string

결제 예정 시점