일반 결제 JavaScript SDK

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

SDK 추가

<script> 태그로 설치하기

결제창을 연동할 HTML 페이지에 일반 결제 JavaScript 파일을 추가합니다.

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

index.html
<head>
<title>결제하기</title>
<!-- 1. 스크립트 추가 -->
<script src="https://js.tosspayments.com/v1"></script>
</head>
<script> var clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq' // 테스트용 클라이언트 키 // 2. 초기화 var tossPayments = TossPayments(clientKey) </script>
HTML

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

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

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

패키지 매니저로 설치하기

일반 결제 JavaScript SDK는 npm 패키지로도 제공됩니다. 사용하는 패키지 매니저에 따라 아래 명령어로 SDK를 설치해보세요.

npm install @tosspayments/payment-sdk --save
{
"name": "payments-test",
"version": "1.0.0",
"description": "토스페이먼츠 테스트 프로젝트",
"main": "app.js",
"author": "김토페",
"dependencies": {
"@tosspayments/payment-sdk": "^1.0.0"
}
}
JSON

설치가 잘 되었다면 loadTossPayments 함수를 불러옵니다.

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

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

일반 결제 JavaScript SDK의 npm 패키지는 동적으로 HTML에 https://js.tosspayments.com/v1 코드를 삽입하는 역할을 합니다. 패키지 내부에는 일반 결제 JavaScript SDK 소스 코드를 포함하지 않습니다. 따라서 사용하는 번들러의 번들링 대상에 포함되지 않습니다.

결제 요청 처리

결제창 실행 후 리다이렉트 URL을 받아서 결제 요청 결과를 처리하는 방법입니다.

결제 요청에 성공했을 때

결제 요청에 성공하면 메서드를 호출할 때 파라미터에 포함해서 보냈던 successUrl로 리다이렉트 됩니다.

successUrl에는 paymentKey, orderId, amount 세 가지 쿼리 파라미터가 들어있습니다.

https://{ORIGIN}/success?paymentKey={PAYMENT_KEY}&orderId={ORDER_ID}&amount={AMOUNT}
  • paymentKey: 결제 건에 대한 고유한 키 값입니다.
  • orderId: 상점에서 주문 건을 구분하기 위해 발급한 고유 ID입니다. 결제창을 열 때 requestPayment에 담아 보낸 값입니다.
  • amount: 실제로 결제된 금액입니다.

돌아온 파라미터를 요청 본문으로 포함해 결제 승인 API를 호출할 수 있습니다.

결제 요청에 실패했을 때

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

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

https://{ORIGIN}/fail?code={ERROR_CODE}&message={ERROR_MESSAGE}&orderId={ORDER_ID}
  • code: 오류 타입을 보여주는 에러 코드입니다.
  • message: 에러 메시지입니다. 에러 발생 이유를 알려줍니다.
  • orderId: 상점에서 주문 건을 구분하기 위해 발급한 고유 ID입니다.

브라우저 에러 코드

브라우저에서 failUrl로 전달되는 에러 목록입니다.

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

응답 처리

모든 메서드 응답에 대해 성공 및 에러 처리를 동일한 방식으로 할 수 있습니다.

메서드를 실행하면 Promise 객체가 응답으로 돌아옵니다. Promisecatch 블록에서 reject 된 에러를 아래와 같이 직접 처리할 수 있습니다.

예시
// * 결제 정보 파라미터로 넘긴 카드 코드가 유효하지 않을 때
tossPayments
.requestPayment('카드', {
// 결제 정보 파라미터
})
.catch(function (error) {
if (error.code === 'USER_CANCEL') {
// 결제 고객이 결제창을 닫았을 때 에러 처리
} else if (error.code === 'INVALID_CARD_COMPANY') {
// 유효하지 않은 카드 코드에 대한 에러 처리
}
})
JavaScript

그 외의 에러는 에러 코드 페이지에서 살펴보세요.

메서드

일반 결제 JavaScript SDK에서 제공하는 메서드 목록입니다. 각 메서드의 용도와 파라미터를 살펴보세요.

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

requestPayment를 실행하면 결제창이 열립니다.

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

tossPayments.requestPayment('카드', {
amount: 15000,
orderId: '',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: 'http://localhost:8080/success',
failUrl: 'http://localhost:8080/fail',
})
JavaScript

결제 수단(한글·영문)

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

결제 정보

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

  • amount 필수 · number

    결제되는 금액입니다.

  • orderId 필수 · string

    상점에서 주문 건을 구분하기 위해 발급한 고유 ID입니다. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.

  • orderName 필수 · string

    결제에 대한 주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.

  • successUrl 필수 · string

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

  • failUrl 필수 · string

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

  • windowTarget string

    브라우저에서 결제창이 열리는 프레임을 지정합니다. self, iframe 중 하나입니다.

    값을 넣지 않으면 iframe에서 결제창이 열립니다. 현재창에서 결제창으로 이동시키는 방식을 사용하려면 값을 self로 지정하세요.

    * 모바일 웹에서는 windowTarget 값과 상관없이 항상 현재창에서 결제창으로 이동합니다.

  • customerName string

    고객의 이름입니다. 최대 길이는 100자입니다.

  • customerEmail string

    고객의 이메일 주소입니다. 최대 길이는 100자입니다.

  • taxFreeAmount number

    결제할 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.

    *면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점인 경우에는 적용되지 않습니다. 더 자세한 내용은 복합 과세 처리하기에서 살펴보세요.

  • cultureExpense boolean

    문화비로 지출했는지 여부입니다. (도서구입, 공연 티켓, 박물관·미술관 입장권 등)

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

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

requestBillingAuth를 실행하면 자동 결제 등록창이 열립니다. 결제 정보를 등록해두고 상점에서 원하는 시점에 자동으로 결제하는 자동 결제 연동에 사용합니다.

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

tossPayments.requestBillingAuth('카드', {
customerKey: '',
successUrl: 'http://localhost:8080/success',
failUrl: 'http://localhost:8080/fail',
})
JavaScript

결제 수단(한글·영문)

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

  • 카드/CARD

결제 정보

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

  • customerKey 필수 · string

    상점에서 고객을 구분하기 위해 발급한 고객의 고유 ID입니다. 이 값에 빌링키가 연결됩니다. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @로 최소 2자 이상 최대 300자 이하여야 합니다.

  • successUrl 필수 · string

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

  • failUrl 필수 · string

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

  • windowTarget string

    브라우저에서 결제창이 열리는 프레임을 지정합니다. self, iframe 중 하나입니다.

    값을 넣지 않으면 iframe에서 결제창이 열립니다. 현재창에서 결제창으로 이동시키는 방식을 사용하려면 값을 self로 지정하세요.

    * 모바일 웹에서는 windowTarget 값과 상관없이 항상 현재창에서 결제창으로 이동합니다.

내용이 도움 되셨나요?
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기