JavaScript SDK

TossPayments.js는 브라우저 환경에서 사용할 수 있는 SDK(Software Development Kit)로, 결제창을 열 수 있는 메서드를 제공합니다. SDK 사용을 위한 준비와 메서드 사용법, 결제 실패 및 에러 처리 방법을 알아봅니다.

SDK 추가

개발환경에 따라 설치할 수 있도록 스크립트로 추가하는 방법과 npm 패키지로 설치하는 방법 두가지를 지원합니다.

스크립트로 추가하기

결제창을 연동할 HTML 페이지에 TossPayments.js JavaScript 파일을 스크립트로 추가합니다.

스크립트 로드가 완료되면 전역 객체(window)TossPayments가 생성됩니다. 이 함수를 이용해서 다음 단계인 초기화를 진행할 수 있습니다.

<head>
<title>결제하기</title>
<script src="https://js.tosspayments.com/v1"></script>
</head>

npm으로 설치하기(ES6+)

ES6+ 환경에서 개발하는 경우 npm 패키지로 TossPayments.js를 추가할 수 있습니다. 사용하는 패키지 매니저에 따라 아래 명령어로 SDK를 설치해보세요.

npm install @tosspayments/sdk --save
yarn add @tosspayments/sdk # yarn을 사용하는 경우
{
"name": "payments-test",
"version": "1.0.0",
"description": "토스페이먼츠 테스트 프로젝트",
"main": "app.js",
"author": "김토페",
"dependencies": {
"@tosspayments/sdk": "^1.1.4"
}
}

@tosspayments/sdk 패키지는 CDN에서 제공되고 있는 TossPayments.js JavaScript 파일(https://js.tosspayments.com/v1) 을 동적으로 HTML에 삽입하는 역할을 합니다.

SDK 초기화

초기화는 SDK를 사용하기 위한 설정 작업입니다. 설치된 SDK에 포함된 메서드를 사용할 수 있도록 객체를 만들고, 클라이언트 키 값을 통해 가맹점을 구분하는 과정입니다.

초기화를 위해 SDK에서 제공하는 TossPayments 함수와 가맹점의 클라이언트 키를 사용해서 초기화를 진행해봅니다.

스크립트로 추가한 경우

클라이언트 키를 TossPayments 함수에 넣고 실행하면 초기화 된 객체가 생성됩니다. 테스트용 클라이언트 키로 시작해보세요.

const tossPayments = TossPayments('test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq')

npm으로 설치한 경우(ES6+)

npm으로 설치했다면 먼저 loadTossPayments를 불러와야 합니다.

아래와 같이 loadTossPayments에 클라이언트 키를 넣고 실행하면 TossPayments({clientKey})와 동일하게 초기화된 객체가 생성됩니다.

import { loadTossPayments } from '@tosspayments/sdk'
const clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq'
// async/await을 사용하는 경우
async function main() {
const tossPayments = await loadTossPayments(clientKey)
}
// Promise를 사용하는 경우
loadTossPayments(clientKey).then(tossPayments => {
// ...
})

requestPayment(결제수단, 결제정보)

requestPayment 메서드를 실행하면 결제창을 띄울 수 있습니다.

첫번째 파라미터에는 결제수단, 두번째 파라미터에는 결제정보가 들어갑니다. 결제수단이 달라도 requestPayment를 동일한 방식으로 사용할 수 있습니다.

tossPayments.requestPayment('카드', {
amount: 15000,
orderId: '',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: window.location.origin + '/success',
failUrl: window.location.origin + '/fail',
})

결제수단(한글/영문)

  • '카드'/'CARD'
  • '토스결제'/'TOSSPAY'
  • '계좌이체'/'TRANSFER'
  • '가상계좌'/'VIRTUAL_ACCOUNT'
  • '휴대폰'/'MOBILE_PHONE'
  • '문화상품권'/'CULTURE_GIFT_CERTIFICATE'
  • '도서문화상품권'/'BOOK_GIFT_CERTIFICATE'
  • '게임문화상품권'/'GAME_GIFT_CERTIFICATE'

결제정보

공통 파라미터로 들어가는 결제정보를 살펴보세요.

  • amount 필수 · number

    결제되는 금액입니다.

  • orderId 필수 · string

    가맹점에서 사용하는 해당 주문에 대한 ID입니다. 각 주문마다 유니크해야 합니다.

  • orderName 필수 · string

    결제에 대한 주문명입니다. 예를 들면 '생수 외 1건' 같은 형식입니다.

  • successUrl 필수 · string

    결제가 성공하고 나면 리다이렉트(Redirect)되는 URL입니다. 결제 승인 처리에 필요한 값들이 쿼리 파라미터(Query Parameter)로 함께 전달됩니다. 반드시 오리진(origin)을 포함해야 합니다. 예를 들면 https://www.example.com/success와 같은 형태입니다.

  • failUrl 필수 · string

    결제가 실패하면 리다이렉트되는 URL입니다. 에러코드 및 에러 메시지가 쿼리 파라미터로 함께 전송됩니다. 반드시 오리진(origin)을 포함해야 합니다.

각 결제수단별로 달라지는 파라미터 정보는 아래 링크에서 살펴보세요.

requestBillingAuth('카드', 결제정보)

requestBillingAuth 메서드는 결제정보를 등록해두고 가맹점에서 원하는 시점에 자동으로 결제하는 자동결제 연동에 사용합니다.

현재 지원하는 자동결제 결제수단은 카드입니다. 따라서 결제수단 파라미터는 늘 카드로 고정입니다.

tossPayments.requestBillingAuth('카드', {
customerKey: 'aENcQAtPdYbTjGhtQnNVj',
successUrl: window.location.origin + '/success',
failUrl: window.location.origin + '/fail',
})

requestPayment 메서드의 첫번째 파라미터에는 결제수단, 두번째 파라미터에는 결제정보가 들어갑니다.

결제수단(한글/영문)

  • '카드'/'CARD'

결제정보

자동결제 요청에 필요한 파라미터를 살펴보세요.

  • customerKey 필수 · string

    가맹점에서 사용하는 고객의 고유 ID입니다. 빌링키가 해당 고객에게 할당됩니다.

    영문 대소문자, 숫자, 특수문자 -, _, =, ., @로 최소 2자 이상 최대 255자 이하여야 합니다.

  • successUrl 필수 · string

    결제가 성공하고 나면 리다이렉트(Redirect)되는 URL입니다. 결제승인 처리에 필요한 값들이 쿼리 파라미터(Query Parameter)로 함께 전달됩니다. 반드시 오리진(origin)을 포함해야 합니다. 예를 들면 https://www.example.com/success와 같은 형태입니다.

  • failUrl 필수 · string

    결제가 실패하면 리다이렉트되는 URL입니다. 에러코드 및 에러 메시지가 쿼리 파라미터로 함께 전송됩니다. 반드시 오리진(origin)을 포함해야 합니다.

결제 실패 처리

실패 URL 리다이렉트

결제 승인이 실패하면 메서드를 호출할 때 결제정보 파라미터에 포함해서 보냈던 failUrl으로 리다이렉트 됩니다.

예를 들어 failUrl이 https://example.com/fail인 경우, 리다이렉트 되는 URL은 다음과 같습니다.

https://example.com/fail?code=PAY_PROCESS_CANCELED&message=%EC%82%AC%EC%9A%A9%EC%9E%90%EC%97%90%20%EC%9D%98%ED%95%B4%20%EA%B2%B0%EC%A0%9C%EA%B0%80%20%EC%B7%A8%EC%86%8C%EB%90%98%EC%97%88%EC%8A%B5%EB%8B%88%EB%8B%A4.&orderId=a4CWyWY5m89PNh7xJwhk1

failUrl은 에러코드(code)와 에러 메시지(message), 주문 건을 특정하는 ID(orderId)로 이루어져 있습니다.

  • code: 오류 타입을 보여주는 에러코드입니다.
  • message: 에러 메시지입니다. 에러 발생 이유를 알려줍니다.
  • orderId: 가맹점에서 주문 건에 대해 발급한 고유 ID입니다.

브라우저 에러코드

에러코드설명
PAY_PROCESS_CANCELED사용자에 의해 결제가 취소되었습니다.
PAY_PROCESS_ABORTED결제 진행 중 승인에 실패하여 결제가 중단되었습니다.
REJECT_CARD_COMPANY카드사 승인이 거절되었습니다.

사용자가 결제창을 닫은 경우 에러 처리

사용자가 직접 창 닫기 버튼을 누르면 결제창이 닫히면서 메서드에서 USER_CANCEL 에러를 돌려줍니다.

메서드가 돌려주는 Promise의 catch 블록에서 Reject 된 에러를 이용해 직접 취소 이벤트를 처리할 수 있습니다.

예제 코드

// * 결제창 호출 취소
tossPayments
.requestPayment('카드', {
// ...
})
.catch(function (error) {
if (error.code === 'USER_CANCEL') {
// 취소 이벤트 처리
}
})
// * 자동결제 등록창 취소
tossPayments
.requestBillingAuth('카드', {
// ...
})
.catch(function (error) {
if (error.code === 'USER_CANCEL') {
// 취소 이벤트 처리
}
})
내용이 도움 되셨나요?
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기