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

스마트로

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

스마트로 채널 설정하기

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

가능한 결제 수단

  • 결제창 일반결제

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

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

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

  • API 수기(키인) 결제

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

  • API 빌링키 발급

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

공통 유의사항

주문 번호(paymentId)에 특수문자를 사용할 수 없습니다.

SDK 및 API를 이용하여 결제 요청시 숫자, 문자(알파벳 소문자와 대문자) 또는 그 조합으로 이루어진 거래 번호를 사용해야 합니다.

주문 번호(paymentId)는 최대 40자까지 입력할 수 있습니다.

스마트로의 경우 paymentId는 최대 40자까지 가능하며, 40자가 넘을 경우 40자까지 잘려서 저장됩니다.

결제통화(currency) 파라미터가 적용되지 않습니다.

일반적으로 currency 파라미터를 이용하여 결제통화를 지정할 수 있지만 스마트로의 경우 상점아이디 설정에 따라 사용 가능한 통화가 자동으로 결정됩니다. 따라서 결제 요청 시 currency를 입력하더라도 적용되지 않습니다.

스마트로의 경우 KRWUSD만 지원하며 이 외의 값을 입력하는 경우 에러를 리턴하며 결제가 진행되지 않습니다.

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] 해외 결제 사용

카드 결제

할부 개월수 리스트 제어가 불가능합니다.

일반적으로 card.installment.monthOption.availableMonthList 파라미터를 사용하여 구매자에게 노출할 할부 개월수 리스트를 제어할 수 있으나 스마트로의 경우 해당 기능을 지원하지 않습니다. 추가로 상점 아이디에 무이자 할부 설정에 따라 무이자 정보가 자동 표기됩니다.

카드사 다이렉트 호출 시 할부 개월수를 고정해야합니다.

스마트로의 경우 카드사 다이렉트 호출 파라미터와 고정 할부 개월수는 항상 같이 사용 해야 합니다. 하나의 파라미터만 설정하는 경우 에러가 리턴되며 정상적으로 결제가 진행되지 않습니다.

카드사 포인트 사용 여부 파라미터로 제어가 불가능합니다.

일반적으로 card.useCardPoint 파라미터로 카드사 포인트 사용 여부를 설정할 수 있지만 스마트로는 상점 아이디 설정에 따라 카드사 포인트 사용 여부가 결정됩니다.

일부 카드 다이렉트 호출 시 윈도우 환경에서만 가능합니다.

스마트로의 경우 윈도우 OS에서만 전북 카드(code: 372)와 카카오뱅크 카드(code: 090)로 다이렉트 호출이 가능합니다.

간편 결제

스마트로-네이버페이 결제 시 카드결제만 가능합니다.

스마트로를 통한 네이버페이를 다이렉트로 호출하여 결제하는 경우 등록된 카드로만 결제가 가능하고 네이버페이 포인트/머니 결제는 불가능합니다. 네이버페이 포인트/머니로 결제를 원하시면 결제창 호출 시 결제수단을 카드로 지정하여 호출한 뒤, 결제를 진행해야합니다.

가상계좌 결제

현금영수증 파라미터 사용 시 다이렉트로 호출해야 합니다.

기본적으로 결제창을 통하여 현금성 결제수단(실시간 계좌이체, 가상계좌)으로 결제하는 경우 현금영수증을 발급할 수 있으며, 결제창 내에서 현금영수증 정보(현금영수증 발급 유형, 현금영수증 발행 식별 번호)를 입력할 수 있습니다.

스마트로의 경우 결제 요청 시 virtualAccount.cashReceiptTypevirtualAccount.customerIdentifier를 이용하여 현금영수증 정보를 사전에 정보를 전달할 수 있으며, 전달한 정보는 결제창에 자동 입력됩니다. 단, 이 파라미터를 이용하려면 스마트로 정책상 다이렉트로 호출해야 합니다.

예시코드

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: "VIRTUAL_ACCOUNT",
    virtualAccount: {
      accountExpiry: {
        dueDate: `2024-11-12T23:59:59+09:00`, // 입금기한은 미래시간만 가능합니다.
      },
      cashReceiptType: `PERSONAL`,
      customerIdentifier: `01088325501`,
      bankCode: `KOOOKMIN_BANK`,
    },
  });
}

휴대폰 소액결제

productType 파라미터는 필수 입력해야 합니다.

  • 스마트로의 경우 휴대폰 소액결제시 상품 유형을 구분 짓는 productType 파라미터가 필수로 요구됩니다.
  • productType의 값은 PRODUCT_TYPE_REAL 또는 PRODUCT_TYPE_DIGITAL를 입력해야 합니다.
  • 상품 유형은 스마트로 상점아이디의 설정과 일치해야 합니다. 일치하지 않는 경우 호출한 결제창 내에 에러가 리턴되며, 결제가 불가능합니다.

빌링키 발급

결제창 빌링키 발급 시 한국어만 지원됩니다.

스마트로의 경우 결제창 호출 시 한국어 또는 영어로 지원됩니다만 **빌링키 발급**시에는 한국어만 지원합니다.

휴대폰 본인인증 프로세스를 진행해야 빌링키 발급이 가능합니다.

스마트로의 경우 빌링키 발급시 휴대폰 본인인증 프로세스를 진행해야 합니다. 동일 고객에 한하여 휴대폰 본인인증은 최초 1회만 진행하고 있습니다. 따라서 customerId 파라미터에 고객을 식별할 수 있는 값을 넣어 사용해야 합니다. 단, 동일한 고객이더라도 customerId가 달라지는 경우 휴대폰 프로세스를 다시 진행해야 합니다.

에스크로 결제

에스크로 결제시 카드사/가상계좌 다이렉트 호출 사용이 불가능합니다.

스마트로는 에스크로 결제시 카드사 다이렉트 호출 및 가상계좌 다이렉트 호출이 불가능합니다. 만약 에스크로 결제시 아래와 같이 다이렉트 호출을 할 경우 에러가 리턴되면서 결제창이 호출되지 않습니다.

예시코드

  • V2 에스크로 + 카드사 다이렉트 호출
PortOne.requestPayment({
  storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요.
  channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
  payMethod: "CARD",
  totalAmount: 50000,
  isEscrow: true, // 에스크로 결제
  card: {
    cardCompany: "BC_CARD", // 카드사 다이렉트 호출
    installment: {
      monthOption: {
        fixedMonth: 5,
      },
    },
  },
});
  • V2 에스크로 + 가상계좌 다이렉트 호출
PortOne.requestPayment({
  storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요.
  channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
  payMethod: "VIRTUAL_ACCOUNT",
  virtualAccount: {
    accountExpiry: {
      dueDate: `2024-11-12T23:59:59+09:00`, // 입금기한은 미래시간만 가능합니다.
    },
  },
  totalAmount: 50000,
  isEscrow: true, // 에스크로 결제
  virtualAccount: {
    bankCode: "SHINHAN_BANK", // 은행 다이렉트 호출
  },
});

에스크로 계좌이체 결제시 현금영수증 파라미터 사용이 불가능합니다.

에스크로 결제 시에는 cashReceiptTypecustomerIdentifier 파라미터를 사용할 수 없습니다. 해당 파라미터를 전달하는 경우 에러가 리턴되면서 결제창이 호출되지 않습니다.

예시코드

  • V2 에스크로 + 계좌이체 + 현금영수증 정보 전달
PortOne.requestPayment({
  storeId: "store-4ff4af41-85e3-4559-8eb8-0d08a2c6ceec", // 고객사 storeId로 변경해주세요.
  channelKey: "channel-key-9987cb87-6458-4888-b94e-68d9a2da896d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
  totalAmount: 50000,
  payMethod: "TRANSFER", // 계좌이체 결제
  isEscrow: true, // 에스크로 결제
  transfer: {
    // 현금영수증 정보 전달
    cashReceiptType: "CORPORATE",
    customerIdentifier: "1178178260",
  },
});

기타

서비스 제공기간(offerPeriod) 이용시 시작일(from)과 종료일(to)를 모두 입력해야 합니다.

결제창 내 서비스 제공 기간 노출을 원하는 경우 offerPeriod를 이용하여 제어할 수 있습니다. 해당 파라미터 이용시에는 fromto 파라미터를 모두 입력해야 결제창에 정상적으로 노출됩니다.

현금영수증 관련 파라미터 사용시 발급 유형( cashReceiptType)에 따라 발행 대상 식별 정보(customerIdentifier)를 올바르게 입력해야 합니다.

cashReceiptType: ANONYMOUS일 때, customerIdentifier에 값을 입력하거나 cashReceiptType: PERSONAL 혹은 cashReceiptType: CORPORATE일 때, customerIdentifier에 값을 입력하지 않으면 에러가 리턴되면서 결제창이 호출되지 않습니다.

SDK 결제 FAQ

[테스트연동] 부분취소는 안되나요?

테스트 모드로 연동한 채널을 이용하여 결제한 체크카드 거래건의 경우 전액 취소만 가능하며 부분취소는 불가능합니다.

[테스트연동] 국민카드/카카오뱅크카드 사용 시 결제가 자꾸 실패해요.

테스트 모드로 연동한 채널을 이용하는 경우 국민카드 또는 카카오뱅크로 결제가 불가능합니다. 다른 카드사의 카드로 테스트 해보시길 바랍니다.

[테스트연동] 카카오페이/페이코 결제 시 결제가 안돼요

테스트 모드로 연동한 채널을 이용하여 카카오페이 또는 페이코 결제 시 삼성/현대/농협/신한 카드만 사용이 가능합니다. 이 외의 카드는 결제가 불가능합니다.

[테스트연동] Kbank로 가상계좌 발급이 불가능해요

테스트 모드로 연동한 채널을 이용하여 가상계좌 발급 요청시 Kbank, 국민은행, 전북은행, 광주은행, 대구은행 등 일부 은행에서는 발급이 불가능합니다.

[테스트연동] 카카오페이 결제 시 자동으로 취소가 되나요?

테스트 모드로 연동한 채널을 이용하여 카카오페이 결제 시 자동취소가 불가능합니다. 테스트 결제 건에 대해 직접 취소처리 하셔야 합니다. 취소는 포트원 콘솔 내 결제내역 혹은 결제 취소 API (POST /payments/{paymentId}/cancel)를 이용하여 취소할 수 있습니다.

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: {
    paymentId: `payment${crypto.randomUUID()}`,
    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 string

        인증 관련 정보

        • number object

          카드 번호

        • expiryYear object

          유효 기간 만료 연도 (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}/schedule`,
  method: "post",
  headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
  data: {
    payment: {
      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

    결제 예정 시점