API & SDK/결제위젯/JavaScript
목차

결제위젯 JavaScript SDK는 브라우저 환경에서 사용할 수 있는 결제위젯 메서드를 제공합니다. SDK를 추가하고 메서드를 사용하는 방법을 알아봅니다.

샘플 프로젝트Next.js, Node, React 샘플 프로젝트를 확인하세요.

SDK 설치 및 초기화

<script> 태그에 결제위젯 SDK 파일을 추가합니다. 스크립트가 로드되면 전역 객체(window)에 생기는 PaymentWidget() 초기화 함수에 파라미터를 설정해서 결제위젯 객체를 생성하세요.

checkout.html
HTML
<head>
<meta charset="utf-8" />
<!-- 1. 스크립트 추가 -->
<script src="https://js.tosspayments.com/v1/payment-widget"></script>
</head>
<body>
<script> const clientKey = 'test_gck_docs_Ovk5rk1EwkEbP0W43n07xlzm' // 테스트용 클라이언트 키 const customerKey = '' // 내 상점에서 고객을 구분하기 위해 발급한 고객의 고유 ID // 2. 결제위젯 SDK 초기화 const paymentWidget = PaymentWidget(clientKey, customerKey) // 회원 결제 // const paymentWidget = PaymentWidget(clientKey, PaymentWidget.ANONYMOUS) // 비회원 결제 </script>
</body>

결제위젯 초기화 파라미터

  • clientKey 필수 · string

    클라이언트 키는 브라우저에서 결제창을 연동할 때 사용합니다. API 키 메뉴에서 확인할 수 있는 결제위젯 연동 키 > 클라이언트 키입니다.

  • customerKey 필수 · string

    구매자 ID입니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 를 최소 1개 이상 포함한 최소 2자 이상 최대 50자 이하의 문자열이어야 합니다.

    비회원 결제에는 PaymentWidget.ANONYMOUS를 사용하세요.

  • options object

    결제위젯 추가 옵션입니다.

  • brandpay object

    결제위젯에 브랜드페이를 추가할 때 설정합니다. redirectUrl이 담긴 객체를 넘기세요. redirectUrlAccess Token 발급 과정에서 임시 인증 코드를 받을 URL입니다.

메서드

결제위젯 JavaScript SDK에서 제공하는 메서드 목록입니다.

renderPaymentMethods(선택자, 결제 금액, 옵션?)

결제 UI를 렌더링하는 메서드입니다. 주문서의 DOM이 생성된 이후에 호출하세요. 응답으로 결제 UI 인스턴스가 돌아옵니다.

JavaScript
const paymentMethodsWidget = paymentWidget.renderPaymentMethods(
'#payment-method',
{
value: 10000,
currency: 'KRW',
country: 'KR',
},
{ variantKey: 'widgetA' }
)

파라미터

  • selector 필수 · string

    결제 UI를 렌더링할 위치를 지정합니다. <div>와 같은 HTML 요소를 선택할 수 있는 CSS 선택자를 사용합니다.

    예를 들어 <div id="payment-method">에 결제 UI를 렌더링하려면, #payment-method를 전달해야 합니다.

  • amount 필수 · object

    결제 금액 정보입니다.

  • value 필수 · number

    결제 금액입니다.

    PayPal 해외간편결제를 연동한다면 소수점 두 번째 자리까지만 허용됩니다.

  • currency string

    결제 통화입니다. 기본 값은 KRW입니다.

    PayPal 해외간편결제를 연동한다면 필수 값입니다. PayPal에서 사용할 수 있는 통화는 USD 입니다.

  • country string

    결제한 국가입니다. 기본 값은 KR입니다.

    PayPal 해외간편결제를 연동한다면 필수 값입니다. ISO-3166의 두 자리 국가 코드를 모두 지원합니다.

  • options object

    결제위젯의 렌더링 옵션입니다.

  • variantKey string

    멀티 결제 UI를 사용할 때 설정합니다. 렌더링하고 싶은 결제 UI의 키 값을 넣으세요.

응답


결제 UI 인스턴스를 반환합니다. 해당 인스턴스로 아래 메서드를 호출하세요.

  • updateAmount(): 결제 UI가 렌더링된 이후에 결제 금액을 업데이트할 수 있는 메서드입니다.
  • getSelectedPaymentMethod(): 구매자가 선택한 결제수단을 확인할 수 있습니다.
  • on(): 결제 UI 렌더링 이벤트, 커스텀 결제수단 이벤트를 받을 수 있는 메서드입니다.

updateAmount(결제 금액)

변경된 결제 금액을 UI에 업데이트하는 메서드입니다.

결제 금액이 바뀌면 할부 적용, 즉시 할인 적용 여부도 바뀔 수 있습니다. updateAmount() 메서드로 결제 금액을 변경하고 결제위젯의 할인 정보도 업데이트하세요.

JavaScript
const paymentMethodsWidget = paymentWidget.renderPaymentMethods()
paymentMethodsWidget.updateAmount(50000)

파라미터

  • amount 필수 · number

    새로운 결제 금액입니다.

getSelectedPaymentMethod()

고객이 선택한 결제수단을 전달하는 메서드입니다. renderPaymentMethods()가 반환하는 인스턴스로 호출할 수 있는 메서드입니다.

JavaScript
const paymentMethodsWidget = paymentWidget.renderPaymentMethods()
const selectedPaymentMethod = paymentMethodsWidget.getSelectedPaymentMethod()

응답

다음 필드를 포함하는 객체가 반환됩니다.

  • type string

    결제 타입 정보입니다. NORMAL(일반결제), BRANDPAY(브랜드페이), KEYIN(키인 결제), CUSTOM(커스텀 결제수단) 중 하나입니다.

  • method string

    결제수단입니다. 카드, 가상계좌, 간편결제, 휴대폰, 계좌이체, 문화상품권, 도서문화상품권, 게임문화상품권, 해외간편결제 중 하나입니다.

  • easyPay object

    결제수단이 간편결제일 때 반환되는 정보입니다.

  • provider string

    선택한 간편결제사 코드입니다.

  • paymentMethodKey string

    결제 타입이 CUSTOM일 때 반환되는 커스텀 결제수단 키입니다.

  • methodId string

    결제 타입이 BRANDPAY일 때 반환되는 값입니다. 현재 브랜드페이에서 선택되어 있는 결제수단의 ID입니다.

requestPayment(결제 정보)

고객이 선택한 결제수단의 결제창을 띄우는 메서드입니다. 결제 요청의 응답을 처리하는 방법을 알아보세요.

JavaScript
paymentWidget.requestPayment({
orderId: 'AD8aZDpbzXs4EQa-UkIX6',
orderName: '토스 티셔츠 외 2건',
successUrl: 'http://localhost:8080/success',
failUrl: 'http://localhost:8080/fail',
customerEmail: 'customer123@gmail.com',
customerName: '김토스',
})

파라미터

  • orderId 필수 · string

    주문번호입니다. 주문을 구분하는 ID입니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.

  • orderName 필수 · string

    구매상품입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.

  • successUrl 필수 · string

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

  • failUrl 필수 · string

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

  • customerEmail string

    구매자의 이메일 주소입니다. 결제 상태가 바뀌면 이메일 주소로 결제내역이 전송됩니다. 최대 길이는 100자입니다.

  • customerName string

    구매자명입니다. 최대 길이는 100자입니다.

  • appScheme string

    웹뷰로 연동할 때 상점의 앱 스킴을 지정하면 외부 앱(페이북/ISP)에서 상점 앱으로 돌아올 수 있습니다. 예를 들면 testapp://같은 형태입니다.

  • useInternationalCardOnly boolean

    해외카드(Visa, MasterCard, JCB, UnionPay 등) 결제 여부입니다. 값이 true면 해외카드 결제가 가능한 다국어 결제창이 열립니다.해외 결제 연동 가이드를 참고하세요.

  • taxFreeAmount number

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

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

  • taxExemptionAmount number

    과세를 제외한 결제 금액(컵 보증금 등)입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다. 카드 결제 또는 간편결제로 계좌이체할 때 사용하세요.

    * 과세 제외 금액이 있는 카드 결제는 부분 취소가 안 됩니다.

  • cultureExpense boolean

    , 결제일 때 적용할 수 있는 문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다.

  • useEscrow boolean

    , 결제일 때 적용할 수 있는 사용 여부입니다. 값을 주지 않으면 결제창에서 고객이 직접 에스크로 결제 여부를 선택합니다.

  • escrowProducts array

    각 상품의 상세 정보 객체를 담는 배열입니다. , 에서 에스크로를 사용하는 상점이라면 필수 파라미터입니다.

    예를 들어 사용자가 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다.

  • id string

    상품의 ID입니다. 이 값은 유니크해야 합니다.

  • name string

    상품 이름입니다.

  • code string

    상점에서 사용하는 상품 관리 코드입니다.

  • unitPrice number

    상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격입니다.

  • quantity number

    상품 구매 수량입니다.

  • customerMobilePhone string

    구매자의 휴대폰 번호입니다. 결제에는 입금 안내가 전송되고, 퀵계좌이체창에서는 구매자의 휴대폰 번호를 자동 완성합니다.

  • showCustomerMobilePhone boolean

    결제창에서 휴대폰 번호 입력 필드 노출 여부입니다. false를 넘기면 가상계좌 결제창에서 휴대폰 번호 입력 필드를 보여주지 않습니다. 기본값은 true 입니다.

  • mobileCarrier array

    창에서 선택할 수 있는 통신사를 제한합니다. 배열에 통신사 코드를 추가하면 해당 통신사 코드만 선택할 수 있는 결제창이 뜹니다.

    값을 넣지 않으면 모든 통신사 코드를 선택할 수 있는 결제창이 뜹니다. 통신사 코드를 참고하세요.

판매자 보호 및 위험 관리 파라미터

아래 파라미터는 PayPal 해외간편결제를 사용하면 필수 파라미터입니다. 판매자를 보호하고 위험한 거래를 관리하기 위해 PayPal에 제공되는 정보입니다. 이 파라미터를 보내면 PayPal에서 제공하는 판매자 보호를 받을 수 있으니 반드시 보내주세요.

  • products array

    고객이 구매한 각 상품의 상세 정보 객체를 담는 배열입니다. 예를 들어 고객이 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다.

    products 정보는 필수가 아니지만 이 정보를 보내려면 아래 항목은 모두 필수입니다.

  • name 필수 · string

    상품 이름입니다.

  • quantity 필수 · number

    상품 구매 수량입니다.

  • unitAmount 필수 · number

    상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격입니다.

  • currency 필수 · string

    상품 가격의 통화입니다.

  • description 필수 · string

    상품에 대한 부가적인 설명입니다.

  • shipping object

    고객이 구매한 각 상품의 배송 정보 객체입니다.

  • fullName string

    구매자명입니다.

  • address object

    배송지 주소입니다.

  • country 필수 · string

    배송지 국가 정보입니다.

  • line1 string

    배송지 상세 주소입니다. 도로명 및 건물(Street, Apt), 번지 정보입니다. 예를 들어 2nd St 105 같은 형태입니다.

  • line2 string

    추가적인 배송지 상세 주소입니다. 번지 및 동 호수 정보가 길어질 때 사용합니다. 예를 들어 Unit #105 같은 형태입니다.

  • area1 string

    배송지 주소입니다. 주(State, Province, Region) 정보입니다. 국가 별로 도시 체계에 따라 없는 경우가 있습니다.

  • area2 필수 · string

    배송지 주소입니다. 도시(City) 정보입니다. 예를 들어 San Jose 같은 형태입니다.

  • postalCode string

    배송지 우편번호입니다. 중국, 일본, 프랑스, 독일 등 일부 국가에서 일어나는 PayPal 거래에는 postalCode가 필수 파라미터입니다.

  • paymentMethodOptions object

    결제수단의 추가 파라미터를 담는 객체입니다. 결제수단이나 결제사 별로 파라미터를 제공합니다. PayPal을 연동할 때는 paypal을 사용합니다.

  • paypal object

    PayPal의 추가 파라미터를 담는 객체입니다.

  • setTransactionContext object

    PayPal에서 추가로 요청하는 STC(Set Transaction Context) 정보를 객체로 전달하는 필드입니다. 이 정보는 PayPal에서 부정거래, 결제 취소, 환불 등 리스크 관리에 활용합니다. 결제 거래의 안전성과 신뢰성을 확보하려면 이 정보를 전달해야 합니다. PayPal STC 문서를 참고해서 업종에 따라 필요한 파라미터를 추가해주세요. 문서의 표에 있는 ‘Data Field Name’ 컬럼 값을 객체의 ‘key’로, ‘Description’에 맞는 값을 객체의 ‘value’로 넣어주시면 됩니다.

    예를 들어 이벤트/티케팅 업종에 종사하고 있다면, STC 문서 3페이지에 해당하는 모든 파라미터를 setTransactionContext 객체에 추가하세요.

    * 이 정보는 토스페이먼츠에서 관리하지 않습니다.

응답


requestPayment() 메서드의 응답은 리다이렉트 URL 또는 Promise로 받을 수 있습니다. 자세한 응답 데이터를 확인하세요.

  • 결제 요청이 성공하면 paymentType, paymentKey, orderId, amount가 반환됩니다. 결제 금액이 맞는지 확인하고 결제를 완료하기 위해 결제 승인 API를 호출하세요.
  • 결제 요청이 실패하면 에러 코드와 메시지가 반환됩니다.

on(이벤트, 콜백)

결제위젯의 렌더 이벤트 및 커스텀 결제수단 또는 간편결제 직연동을 추가하는 메서드입니다.

JavaScript
const paymentMethods = paymentWidget.renderPaymentMethods('#payment-method', {
value: 10000,
})
paymentMethods.on('ready', () => {
// 결제 버튼 활성화
})
/* 커스텀 결제수단*/
paymentMethods.on('customRequest', paymentMethodKey => {
if (paymentMethodKey === 'VOUCHER') {
// 상점관리자에서 설정한 key값
// 평생교육바우처로 결제하는 코드
}
})
paymentMethodsWidget.on('customPaymentMethodSelect', paymentMethodKey => {
if (paymentMethodKey === 'VOUCHER') {
// 평생교육바우처 선택했을 때 바우처 입력 폼을 노출
}
})
paymentMethodsWidget.on('customPaymentMethodUnselect', paymentMethodKey => {
if (paymentMethodKey === 'VOUCHER') {
// 평생교육바우처 선택을 해제했을 때 바우처 입력 폼을 숨김
}
})

파라미터

  • eventName 필수 · string
    • ready: 결제 UI 렌더 완료 이벤트입니다. 렌더 완료를 확인하고 requestPayment() 메서드를 호출하세요.
    • customRequest: 결제위젯에 커스텀 결제수단을 추가하는 이벤트입니다.
    • customPaymentMethodSelect: 고객이 커스텀 결제수단을 선택한 이벤트입니다.
    • customPaymentMethodUnselect: 고객이 커스텀 결제수단 선택을 해제한 이벤트입니다.
  • paymentMethodKey 필수 · string

    추가한 결제수단의 키 값입니다.

이용약관 메서드

renderAgreement(선택자, 옵션?)

이용약관 UI를 렌더링하는 메서드입니다. 이용약관 UI에는 토스페이먼츠의 필수 이용약관이 있습니다. 결제위젯 어드민에서 내 상점의 필수 약관, 회원·비회원 약관, 영문 약관 등 약관을 자유롭게 커스터마이징할 수 있습니다.

JavaScript
const paymentAgreement = paymentWidget.renderAgreement('#agreement', { variantKey: 'AGREEMENT' })

파라미터

  • selector 필수 · string

    약관 UI를 렌더링할 위치를 지정합니다. <div>와 같은 HTML 요소를 선택할 수 있는 CSS 선택자를 사용합니다.

    예를 들어 <div id="agreement">에 약관 UI를 렌더링하려면, #agreement를 전달해야 합니다.

  • options string

    이용약관 UI의 렌더링 옵션입니다.

  • variantKey string

    렌더링하고 싶은 이용약관의 키 값을 넣으세요. 결제 UI의 variantKey와 독립적으로 사용됩니다. 이용약관은 결제위젯 어드민에서 추가할 수 있어요.

응답


이용약관 UI 인스턴스를 반환합니다. 해당 인스턴스로 아래 메서드를 호출하세요.

  • getAgreementStatus(): 고객의 이용약관 동의 상태를 응답하는 메서드입니다.
  • on(): 고객 이용약관 동의 이벤트에 콜백을 등록하는 메서드입니다.

getAgreementStatus()

고객의 필수 이용약관에 동의 상태를 나타내는 메서드입니다. 메서드를 호출하면 약관 데이터 객체가 돌아옵니다.

JavaScript
const paymentAgreement = paymentWidget.renderAgreement('#agreement')
paymentAgreement.getAgreementStatus().agreedRequiredTerms // 고객이 모든 필수 약관에 동의했을 경우 true

응답

다음 필드를 포함하는 객체가 반환됩니다.

  • agreedRequiredTerms boolean

    고객이 모든 필수 약관에 동의했는지 알려줍니다.

  • terms array

    개별 약관에 동의했는지 알려줍니다.

  • id string

    약관의 식별자입니다.

  • agreed boolean

    약관의 고객 동의 여부입니다.

  • required boolean

    약관의 필수 여부입니다.

on(이벤트, 콜백)

고객 이용약관 동의 이벤트에 콜백을 등록하는 메서드입니다.

JavaScript
const paymentAgreement = paymentWidget.renderAgreement('#agreement')
const agreementStatus = paymentAgreement.getAgreementStatus()
paymentAgreement.on('change', agreementStatus => {
console.log(agreementStatus.agreedRequiredTerms) // 고객이 모든 필수 약관에 동의했을 경우 true
})

파라미터

  • eventName 필수 · string

    약관 동의와 관련된 이벤트 이름입니다. 현재 지원하는 이벤트는 change입니다.

  • callback 필수 · function

    이벤트의 콜백입니다. 약관 데이터 객체를 콜백으로 전달합니다.

결제 요청 응답 처리

requestPayment() 메서드 응답은 리다이렉트 URL 또는 Promise로 처리할 수 있습니다.

리다이렉트 URL로 처리하기

✔️ PC 및 모바일 환경에서 사용하세요.

✔️ requestPayment()successUrl, failUrl 파라미터를 설정하세요.

✔️ 응답 데이터successUrl, failUrl의 쿼리 파라미터로 확인하세요.

주문서
JavaScript
paymentWidget
.requestPayment({
amount: 15000,
orderId: '',
orderName: '토스 티셔츠 외 2건',
// 테스트에서는 성공, 실패 페이지가 없어도 URL에서 쿼리 파라미터를 확인할 수 있어요.
successUrl: 'http://localhost:8080/success', // 성공 리다이렉트 URL
failUrl: 'http://localhost:8080/fail', // 실패 리다이렉트 URL
})
// 결제창을 띄울수 없는 에러가 발생하면 리다이렉트 URL로 에러를 받을 수 없어요.
.catch(function (error) {
if (error.code === 'INVALID_ORDER_NAME') {
// 유효하지 않은 'orderName' 처리하기
} else if (error.code === 'INVALID_ORDER_ID') {
// 유효하지 않은 'orderId' 처리하기
}
})

✅ 결제 요청 성공: successUrl로 리다이렉트 됩니다. 쿼리 파라미터로 결제 승인 API를 호출하세요.

https://{ORIGIN}/success?paymentKey={PAYMENT_KEY}&orderId={ORDER_ID}&amount={AMOUNT}&paymentType={PAYMENT_TYPE}

❎ 결제 요청 실패: failUrl로 리다이렉트 됩니다. 에러 목록을 확인하세요.

https://{ORIGIN}/fail?code={ERROR_CODE}&message={ERROR_MESSAGE}&orderId={ORDER_ID}

결제창을 띄운 뒤 결제를 취소하면 failUrl로 리다이렉트 되는 것을 확인할 수 있습니다.

아니요. 해시 라우팅 방식을 사용한다면 리다이렉트 URL을 처리할 수 없으니 유의해주세요.

Promise로 처리하기

✔️ PC 환경에서만 사용하세요. 모바일 환경에서 Promise를 사용하면 결제가 안 됩니다.

✔️ requestPayment()successUrl, failUrl, windowTarget 파라미터를 설정하지 마세요.

✔️ 응답 데이터then, catch로 확인하세요.

예시
JavaScript
paymentWidget
.requestPayment({
// 결제 정보 파라미터
// successUrl, failUrl, windowTarget 파라미터를 넘기지 마세요.
})
.then(function (data) {
// 성공 처리: 서버 측에서 결제 승인 API를 호출하세요
})
.catch(function (error) {
// 에러 처리: 에러 목록을 확인하세요
// https://docs.tosspayments.com/reference/error-codes#failurl로-전달되는-에러
if (error.code === 'USER_CANCEL') {
// 결제 고객이 결제창을 닫았을 때 에러 처리
} else if (error.code === 'INVALID_CARD_COMPANY') {
// 유효하지 않은 카드 코드에 대한 에러 처리
}
})

응답 데이터

성공 응답

  • paymentKey string

    결제를 식별하는 키 값입니다. 토스페이먼츠에서 발급합니다. 결제 승인, 결제 조회, 결제 취소 등 운영에 필요한 값입니다.

  • orderId string

    주문번호입니다. 결제 요청에 보낸 값입니다.

  • amount number

    결제 금액입니다. 결제 요청에 보낸 결제 금액과 같은지 반드시 확인해보세요. 클라이언트에서 결제 금액을 조작해 승인하는 행위를 방지할 수 있습니다. 만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요. 적립금이나 쿠폰이 적용된 금액이 맞는지도 확인해보세요.

  • paymentType string

    결제 유형입니다. NORMAL, BRANDPAY, KEYIN 중 하나입니다.

실패 응답

  • code string

    에러 코드입니다. 에러 목록을 확인하세요.

  • message string

    에러 메시지입니다.

  • orderId string

    주문번호입니다. 결제 요청에 담아 보낸 값입니다.

  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    실시간 문의|이메일 보내기