결제위젯 JavaScript SDK는 브라우저 환경에서 사용할 수 있는 결제위젯 메서드를 제공합니다. SDK를 추가하고 메서드를 사용하는 방법을 알아봅니다.
<script>
태그에 결제위젯 SDK 파일을 추가합니다. 스크립트가 로드되면 전역 객체(window)에 생기는 PaymentWidget()
초기화 함수에 파라미터를 설정해서 결제위젯 객체가 생성하세요.
<head>
<meta charset="utf-8" />
<!-- 1. 스크립트 추가 -->
<script src="https://js.tosspayments.com/v1/payment-widget"></script>
</head>
<body>
<script>
const clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq' // 테스트용 클라이언트 키
const customerKey = '' // 고객을 식별할 수 있는 키
// 2. 결제위젯 SDK 초기화
const paymentWidget = PaymentWidget(clientKey, customerKey) // 회원 결제
// const paymentWidget = PaymentWidget(clientKey, PaymentWidget.ANONYMOUS) // 비회원 결제
</script>
</body>
- clientKey 필수 · string
클라이언트 키는 브라우저에서 결제창을 연동할 때 사용합니다. 토스페이먼츠에서 발급합니다. API 키 페이지에서 결제위젯 MID로 발급된 키 값을 사용하세요.
- customerKey 필수 · string
고객 ID입니다. 충분히 무작위한 값을 직접 생성해서 사용하세요. 영문 대소문자, 숫자, 특수문자
-
,_
,=
,.
,@
로 이루어진 1자 이상 50자 이하의 문자열입니다. 비회원 결제에는PaymentWidget.ANONYMOUS
를 사용하세요. - options object
결제위젯에 추가할 옵션입니다.
- brandpay object
결제위젯에 브랜드페이를 추가할 때 설정합니다.
redirectUrl
이 담긴 객체를 넘기세요.redirectUrl
은 Access Token 발급 과정에서 임시 인증 코드를 받을 URL입니다.
결제위젯 JavaScript SDK에서 제공하는 메서드 목록입니다. 모든 메서드는 응답으로 Promise 객체를 반환합니다.
결제수단 UI를 렌더링하는 메서드입니다.
const paymentMethods = paymentWidget.renderPaymentMethods('#payment-method', 15000, { variantKey: "widgetA" });
- selector 필수 · string
- amount 필수 · number
결제할 금액입니다.
- options object
결제위젯의 렌더링 옵션입니다.
- variantKey string
멀티 결제 UI를 사용할 때 설정합니다. 렌더링하고 싶은 결제위젯의 키 값을 넣으세요.
고객이 선택한 결제수단의 결제창을 띄우는 메서드입니다. 결제 요청의 응답을 처리하는 방법을 알아보세요.
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://
같은 형태입니다. - taxFreeAmount number
결제할 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인
0
으로 설정됩니다.*면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점인 경우에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.
- taxExemptionAmount integer
결제 금액 중 과세 제외 금액(컵 보증금 등)입니다. 값을 넣지 않으면 기본값인
0
으로 설정됩니다. 카드 결제 또는 간편결제로 계좌이체할 때 사용하세요.* 과세 제외 금액이 있는 카드 결제는 부분 취소가 안 됩니다.
- cultureExpense boolean
문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다.
- useEscrow boolean
에스크로 사용 여부입니다. 값을 주지 않으면 결제창에서 고객이 직접 에스크로 결제 여부를 선택합니다.
- escrowProducts array
각 상품의 상세 정보 객체를 담는 배열입니다. 가상계좌, 계좌이체에서 에스크로를 사용하는 상점이라면 필수 파라미터입니다.
예를 들어 사용자가 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다.
- id string
상품의 ID입니다. 이 값은 유니크해야 합니다.
- name string
상품 이름입니다.
- code string
상점에서 사용하는 상품 관리 코드입니다.
- unitPrice number
상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격입니다.
- quantity number
상품 구매 수량입니다.
- id string
- customerMobilePhone string
고객의 휴대폰 번호입니다. 가상계좌 입금 안내가 전송되는 번호입니다.
- showCustomerMobilePhone boolean
가상계좌 결제창에서 휴대폰 번호 입력 필드를 보여줄 지 여부입니다.
false
를 넘기면 가상계좌 결제창에서 휴대폰 번호 입력 필드를 보여주지 않습니다. 기본값은true
입니다. - mobileCarrier array
휴대폰 결제창에서 선택할 수 있는 통신사를 제한합니다. 배열에 통신사 코드를 추가하면 해당 통신사 코드만 선택할 수 있는 결제창이 뜹니다.
값을 넣지 않으면 모든 통신사 코드를 선택할 수 있는 결제창이 뜹니다. 통신사 코드를 참고하세요.
변경된 결제 금액을 UI에 업데이트하는 메서드입니다.
결제 금액이 바뀌면 할부 적용, 즉시 할인 적용 여부도 바뀔 수 있습니다. updateAmount()
메서드로 결제 금액을 변경하고 결제위젯의 할인 정보도 업데이트하세요.
paymentMethods.updateAmount(50000);
- updatedAmount 필수 · number
새로운 결제 금액입니다.
결제위젯에 커스텀 결제수단 또는 간편결제 직연동을 추가하는 메서드입니다.
const paymentMethods = paymentWidget.renderPaymentMethods('#payment-method', 10_000)
/* 커스텀 결제수단*/
paymentMethods.on('customRequest', paymentMethodKey => {
if (paymentMethodKey === 'VOUCHER') { // 상점관리자에서 설정한 key값
// 평생교육바우처로 결제하는 코드
}
})
paymentMethodsWidget.on('customPaymentMethodSelect', paymentMethodKey => {
if (paymentMethodKey === 'VOUCHER') {
// 평생교육바우처 선택했을 때 바우처 입력 폼을 노출
}
})
paymentMethodsWidget.on('customPaymentMethodUnselect', paymentMethodKey => {
if (paymentMethodKey === 'VOUCHER') {
// 평생교육바우처 선택을 해제했을 때 바우처 입력 폼을 숨김
}
})
- eventName 필수 · string
customRequest
: 결제위젯에 커스텀 결제수단을 추가하는 이벤트입니다.customPaymentMethodSelect
: 고객이 커스텀 결제수단을 선택한 이벤트입니다.customPaymentMethodUnselect
: 고객이 커스텀 결제수단 선택을 해제한 이벤트입니다.
- paymentMethodKey 필수 · string
추가한 결제수단의 키 값입니다.
이용약관 UI를 렌더링하는 메서드입니다. 이용약관 UI에는 토스페이먼츠의 필수 이용약관이 있습니다. 상점관리자에서 내 상점의 필수 약관, 회원·비회원 약관을 추가할 수 있습니다.
const paymentAgreement = paymentWidget.renderAgreement('#agreement')
고객의 필수 이용약관에 동의 상태를 나타내는 메서드입니다. 메서드를 호출하면 약관 데이터 객체가 돌아옵니다.
const paymentAgreement = paymentWidget.renderAgreement('#agreement');
paymentAgreement.getAgreementStatus().agreedRequiredTerms; // 고객이 모든 필수 약관에 동의했을 경우 true
- agreedRequiredTerms boolean
고객이 모든 필수 약관에 동의했는지 알려줍니다.
- terms array
개별 약관에 동의했는지 알려줍니다.
- id string
약관의 식별자입니다.
- agreed boolean
약관의 고객 동의 여부입니다.
- required boolean
약관의 필수 여부입니다.
고객 이용약관 동의 이벤트에 콜백을 등록하는 메서드입니다.
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로 처리할 수 있습니다.
✔️ PC 및 모바일 환경에서 사용하세요.
✔️ requestPayment()
의 successUrl
, failUrl
파라미터를 설정하세요.
✔️ 응답 데이터를 successUrl
, failUrl
의 쿼리 파라미터로 확인하세요.
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}
✔️ PC 환경에서만 사용하세요. 모바일 환경에서 Promise를 사용하면 결제가 안 됩니다.
✔️ requestPayment()
의 successUrl
, failUrl
, windowTarget
파라미터를 설정하지 마세요.
✔️ 응답 데이터를 then
, catch
로 확인하세요.
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
주문 ID입니다. 결제 요청에 보낸 값입니다.
- amount number
결제 금액입니다. 결제 요청에 보낸 결제 금액과 같은지 반드시 확인해보세요. 클라이언트에서 결제 금액을 조작해 승인하는 행위를 방지할 수 있습니다. 만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요. 적립금이나 쿠폰이 적용된 금액이 맞는지도 확인해보세요.
- paymentType string
결제 유형입니다.
NORMAL
,BRANDPAY
중 하나입니다.NORMAL
: 일반 결제입니다. 코어 결제 승인 API를 호출해서 결제를 완료하세요.BRANDPAY
: 브랜드페이 결제입니다. 브랜드페이 결제 승인 API를 호출해서 결제를 완료하세요.
- code string
에러 코드입니다. 에러 목록을 확인하세요.
- message string
에러 메시지입니다.
- orderId string
주문 ID입니다. 결제 요청에 담아 보낸 값입니다.