토스페이먼츠

토스페이먼츠 결제 연동 방법을 안내합니다.

채널 설정하기

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

가능한 결제수단

일반 결제
- payMethod파라미터를 결제수단에 따라 아래와 같이 설정해야 합니다.
  - 신용카드 : CARD
  - 실시간 계좌이체 : TRANSFER
  - 가상계좌 : VIRTUAL_ACCOUNT
  - 휴대폰 소액결제 : MOBILE
  - 간편 결제 : EASY_PAY
  - 상품권 결제 : GIFT_CERTIFICATE
빌링키 발급
- billingKeyMethod(빌링키 발급) 파라미터를 CARD로 설정해야 합니다.

SDK 결제 및 빌링키 발급 요청하기

결제 요청 시에는 requestPayment 함수를 호출하고, 빌링키 발급 시에는 requestIssueBillingKey 함수를 호출해야합니다. channelKey 파라미터에 결제 채널 연동 시 입력한 채널 키를 지정하여 토스페이먼츠 연동임을 명시해주세요. 만약 channelKey가 입력되지 않는 경우 pgProvider 파라미터에 입력된 값에 따라 결제 및 빌링키 발급 창이 호출됩니다.

토스페이먼츠 기준으로 작성한 예시 코드는 아래와 같습니다.

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-3b37819a-1c72-4deb-a245-8c810af5403d", // 콘솔 결제 연동 화면에서 채널 연동 시 생성된 채널 키를 입력해주세요.
    payMethod: "CARD",
  });
}

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",
  });
}

API 빌링키 발급 및 예약/반복 결제 요청하기

빌링키를 발급하기 위해서는 POST /billing-keys를 이용하여 빌링키 발급 요청을 해야합니다. 이후 발급된 빌링키로 예약/반복 결제를 하기위해 POST /payments/${PAYMENT_ID_HERE}/schedules 를 이용하여 결제를 예약합니다.

// ... 빌링키 발급
const issueResponse = await axios({
  url: `https://api.portone.io/billing-keys`,
  method: "post",
  headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
  data: {
    channelKey,
    customer: {
      id: customerId,
    },
    method: {
      card: {
        credential: {
          number: cardNumber,
          expiryYear,
          expiryMonth,
          birthOrBusinessRegistrationNumber,
          passwordTwoDigits,
        },
      },
    },
  },
});

async function schedulePayment() {
  // 포트원 결제 예약 API 호출
  const response = await axios({
    url: `https://api.portone.io/payments/${encodeURIComponent(PAYMENT_ID_HERE)}/schedules`,
    method: "post",
    headers: { Authorization: `PortOne ${PORTONE_API_SECRET}` },
    data: {
      payment: {
        billingKey: BILLING_KEY_HERE,
        orderName: "월간 이용권 정기결제",
        customer: {
          id: CUSTOMER_ID_HERE,
          // 고객 정보가 필요한 경우 API 명세에 따라 추가해주세요.
        },
        amount: {
          total: 8900,
        },
        currency: "KRW",
      },
      timeToPay: "2023-08-24T14:15:22Z", // 결제를 시도할 시각
    },
  });
  // 결제 예약 이후 로직을 구성해주세요.
}

주요 파라미터

storeId: string

고객사의 상점을 식별하는 고유한 값입니다.

paymentId: string

고객사가 채번하는 주문 고유 번호로 매번 고유하게 채번되어야 합니다.

orderName: string

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

channelKey: string

콘솔의 결제 연동 메뉴에 표시되는 채널 키를 입력해야 합니다.

totalAmount: number

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

currency: string

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

payMethod: string

결제수단을 구분하는 코드로 원하는 결제수단 값을 입력해야 합니다.

유의할 파라미터 - SDK

결제/빌링키 발급 공통

windowType
- 토스페이먼츠의 경우 PC는 IFRAME, mobile은 REDIRECTION만 지원되며 이외의 다른 방식으로 결제창을 호출할 경우 에러를 리턴합니다.
- windowType 파라미터를 채우지 않을 경우 자동으로 아래와 같이 세팅됩니다.
```
{
  "pc": "IFRAME",
  "mobile": "REDIRECTION"
}
```
locale
- 토스페이먼츠의 경우 KO_KR만 지원합니다. 이외의 값을 넣어도 무시됩니다.
redirectUrl
- 모바일 환경에서 결제 요청 시 REDIRECTION 타입이므로, 필수로 입력해야 합니다.

결제 (`requestPayment`)

easyPay
- easyPayProvider
  - 간편결제 결제 요청 시, 사용하고자 하는 간편 결제사에 따라 아래 목록을 참고하여 easyPayProvider 파라미터를 입력해야 합니다.
    - 페이코 : PAYCO
    - 삼성페이 : SAMSUNGPAY
    - SSG페이 : SSGPAY
    - 카카오페이 : KAKAOPAY
    - 네이버페이 : NAVERPAY
    - L페이 : LPAY
    - 토스페이 : TOSSPAY
    - 애플페이 : APPLEPAY
giftCertificate
- giftCertificateType
- 상품권 결제 요청 시, 사용하고자 하는 상품권 종류에 따라 아래 목록을 참고하여 giftCertificateType 파라미터를 입력해야 합니다.
  - 도서문화상품권 : BOOKNLIFE
  - 스마트문상 ((구)게임문화상품권) : SMART_MUNSANG
  - 문화상품권 : CULTURELAND
paymentId
- 토스페이먼츠를 사용하는 경우 영문 대소문자, 숫자, 특수문자(-,_)만 허용되며, 6자 이상 64자 이하만 가능합니다.
currency
- 토스페이먼츠의 경우 원화 결제만 지원하므로 KRW 이외의 값을 넣으면 에러를 리턴합니다.
isCulturalExpense
- 문화비(도서, 공연, 박물관 등) 지출 여부를 구분하고자 할 때 파라미터를 입력하여 사용할 수 있습니다.
card.installment.monthOption.fixedMonth
- 토스페이먼츠의 경우 현대카드는 1만원, 그 외는 5만원 이상 결제에 대해서만 적용됩니다.
bypass
- 토스페이먼츠에서는 아래의 파라미터를 지원합니다.
- tosspayments
  - discountCode
    - 토스페이먼츠와 고객사 간의 계약에 따라 프로모션을 적용할 수 있습니다.
```
{
  "tosspayments": {
    "discountCode": "즉시 할인 코드(카드사 고유 번호)"
  }
}
```
  - useInternationalCardOnly
    - 해외 카드로만 결제가 가능하도록 설정할 수 있습니다.
```
{
  "tosspayments": {
    "useInternationalCardOnly": true
  }
}
```

빌링키 발급 (`requestIssueBillingKey`)

없음

연동 유의사항