결제창 JavaScript SDK

결제창 JavaScript SDK는 브라우저 환경에서 결제창을 열 수 있는 메서드를 제공합니다. 토스페이먼츠 결제창과 직연동 결제창에서 모두 사용합니다. SDK 사용을 위한 준비와 메서드 사용법, 결제 실패 및 에러 처리 방법을 알아봅니다.

모바일 환경에서는 웹뷰로 연동을 하거나 모바일 SDK를 살펴보세요.

SDK 설치 및 초기화

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

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

초기화 파라미터

clientKey 필수 · string
클라이언트 키는 브라우저에서 결제창을 연동할 때 사용합니다. 토스페이먼츠에서 발급합니다. API 키 페이지에서 결제위젯 MID로 발급된 키 값을 사용하세요.

메서드

결제창 JavaScript SDK에서 제공하는 메서드 목록입니다. 모든 메서드는 응답으로 Promise 객체를 반환합니다.

requestPayment(`카드`, 결제 정보)

카드 결제창을 호출하는 메서드입니다. 첫 번째 파라미터에는 카드/CARD, 두 번째 파라미터에는 결제 정보가 들어갑니다.

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

JavaScript

결제 정보

amount 필수 · number
결제되는 금액입니다.
orderId 필수 · string
주문 ID입니다. 충분히 무작위한 값을 직접 생성해서 사용하세요. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
orderName 필수 · string
주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.
successUrl 필수 · string
결제가 성공하면 리다이렉트되는 URL입니다. 결제 승인 처리에 필요한 값들이 쿼리 파라미터로 함께 전달됩니다. 반드시 오리진을 포함해야 합니다. 예를 들면 https://www.example.com/success와 같은 형태입니다.
failUrl 필수 · string
결제가 실패하면 리다이렉트되는 URL입니다. 에러 코드 및 에러 메시지가 쿼리 파라미터로 함께 전송됩니다. 반드시 오리진을 포함해야 합니다.
windowTarget string
브라우저에서 결제창이 열리는 프레임을 지정합니다. self, iframe 중 하나입니다.
값을 넣지 않으면 iframe에서 결제창이 열립니다. 현재창에서 결제창으로 이동시키는 방식을 사용하려면 값을 self로 지정하세요.
* 모바일 웹에서는 windowTarget 값과 상관없이 항상 현재창에서 결제창으로 이동합니다.
customerName string
고객의 이름입니다. 최대 길이는 100자입니다.
customerEmail string
고객의 이메일 주소입니다. 최대 길이는 100자입니다.
taxFreeAmount number
결제 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.
*면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.
taxExemptionAmount integer
결제 금액 중 과세 제외 금액(컵 보증금 등)입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다. 카드 결제 또는 간편결제로 계좌이체할 때 사용하세요.
* 과세 제외 금액이 있는 카드 결제는 부분 취소가 안 됩니다.
flowMode string
DEFAULT는 카드, 간편결제수단이 있는 기본 결제창을 호출합니다. 기본값입니다.
DIRECT는 앱카드 또는 간편결제사 결제창을 호출합니다. 앱카드를 호출하려면 cardCompany를 설정하세요. 간편결제사 결제창을 호출하려면 easyPay를 설정하세요. 앱카드 또는 간편결제사 결제창을 사용하면 고객에게 직접 토스페이먼츠 이용약관 동의를 받으세요.
cardCompany string
카드사 코드입니다. flowMode 값이 DEFAULT이면 설정한 카드사만 보이는 기본 결제창이 열립니다. flowMode 값이 DIRECT이면 설정한 카드사의 결제창이 열립니다.
easyPay string
간편결제사 코드입니다. flowMode 값이 DIRECT이면 설정한 간편결제사의 결제창이 열립니다.
useInternationalCardOnly boolean
해외카드(Visa, MasterCard, UnionPay) 결제 여부입니다. 값이 true면 해외카드 결제가 가능한 영문 결제창이 열립니다.
cardInstallmentPlan number
카드 결제의 할부 개월 수를 고정해 결제창을 열 때 사용합니다. 결제 금액(amount)이 5만원 이상일 때만 사용할 수 있습니다.
2부터 12사이의 값을 사용할 수 있고, 0이 들어가면 할부가 아닌 일시불로 결제됩니다.
값을 넣지 않으면 결제창에서 전체 할부 개월 수를 선택할 수 있습니다.
maxCardInstallmentPlan number
카드 결제에서 선택할 수 있는 최대 할부 개월 수를 제한합니다. 결제 금액(amount)이 5만원 이상일 때만 사용할 수 있습니다.
2부터 12사이의 값을 사용할 수 있고, 0이 들어가면 할부가 아닌 일시불로 결제됩니다. 만약 값을 6으로 설정한다면 결제창에서 일시불~6개월 사이로 할부 개월을 선택할 수 있습니다.
할부 개월 수를 고정하는 cardInstallmentPlan와 같이 사용할 수 없습니다.
freeInstallmentPlans array
무이자 할부를 적용할 카드사 및 할부 개월 정보입니다. 이 파라미터에 포함된 정보와 고객이 선택한 카드사 및 할부 개월이 매칭되면 무이자 할부가 적용됩니다.
*이 파라미터로 적용된 무이자 할부 비용은 상점이 부담합니다.

company 필수 · string
할부를 적용할 카드사 코드입니다. 카드사 코드를 참고하세요.
months 필수 · array
무이자를 적용할 할부 개월 정보입니다. 할부 개월을 배열에 추가해주세요.
useCardPoint boolean
카드로 결제할 때 설정하는 카드사 포인트 사용 여부입니다. 값을 주지 않거나 값이 false라면 사용자가 카드사 포인트 사용 여부를 결정할 수 있습니다. 이 값을 true로 주면 카드사 포인트 사용이 체크된 상태로 결제창이 열립니다.
useAppCardOnly boolean
이 값을 true로 주면 카드사의 앱카드 결제창만 열립니다.
국민, 농협, 롯데, 삼성, 신한, 우리, 현대 카드에만 true 값을 사용할 수 있습니다.
hideMobileAppHeader boolean
상점 앱에서 결제창의 상단 타이틀 바를 숨길지 결정합니다. true로 설정하면 타이틀 바가 숨겨집니다. 상점 앱에서 결제창의 타이틀 바를 숨기고 자체적으로 만든 내비게이션 바를 사용하기 위해 설정합니다. 기본값은 false 입니다. 앱으로 구현할 때만 사용하세요.
discountCode string
카드사의 할인 코드입니다. flowMode 값이 DIRECT여야 합니다.
카드사 혜택 조회 API로 적용할 수 있는 할인 코드의 목록을 조회하세요.
appScheme string
모바일 ISP 앱에서 상점 앱으로 돌아올 때 사용됩니다. 상점의 앱 스킴을 지정하면 됩니다. 예를 들면 testapp://같은 형태입니다.

requestPayment(`가상계좌`, 결제 정보)

가상계좌 결제창을 호출하는 메서드입니다. 첫 번째 파라미터에는 가상계좌/VIRTUAL_ACCOUNT, 두 번째 파라미터에는 결제 정보가 들어갑니다.

tossPayments.requestPayment('가상계좌', { // 결제수단 파라미터
  // 결제 정보 파라미터
  amount: 15000,
  orderId: '',
  orderName: '토스 티셔츠 외 2건',
  customerName: '박토스',
  successUrl: 'http://localhost:8080/success',
  failUrl: 'http://localhost:8080/fail',
  validHours: 24,
  cashReceipt: {
    type: '소득공제',
  },
})

JavaScript

결제 정보

amount 필수 · number
결제되는 금액입니다.
orderId 필수 · string
주문 ID입니다. 충분히 무작위한 값을 직접 생성해서 사용하세요. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
orderName 필수 · string
주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.
successUrl 필수 · string
결제가 성공하면 리다이렉트되는 URL입니다. 결제 승인 처리에 필요한 값들이 쿼리 파라미터로 함께 전달됩니다. 반드시 오리진을 포함해야 합니다. 예를 들면 https://www.example.com/success와 같은 형태입니다.
failUrl 필수 · string
결제가 실패하면 리다이렉트되는 URL입니다. 에러 코드 및 에러 메시지가 쿼리 파라미터로 함께 전송됩니다. 반드시 오리진을 포함해야 합니다.
windowTarget string
브라우저에서 결제창이 열리는 프레임을 지정합니다. self, iframe 중 하나입니다.
값을 넣지 않으면 iframe에서 결제창이 열립니다. 현재창에서 결제창으로 이동시키는 방식을 사용하려면 값을 self로 지정하세요.
* 모바일 웹에서는 windowTarget 값과 상관없이 항상 현재창에서 결제창으로 이동합니다.
customerName string
고객의 이름입니다. 최대 길이는 100자입니다.
customerEmail string
고객의 이메일 주소입니다. 최대 길이는 100자입니다.
taxFreeAmount number
결제 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.
* 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.
taxExemptionAmount integer
결제 금액 중 과세 제외 금액(컵 보증금 등)입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다. 카드 결제 또는 간편결제로 계좌이체할 때 사용하세요.
* 과세 제외 금액이 있는 카드 결제는 부분 취소가 안 됩니다.
cultureExpense boolean
문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다.
validHours number
가상계좌가 유효한 시간을 의미합니다. 값을 넣지 않으면 기본값 168시간(7일)으로 설정됩니다. 설정할 수 있는 최대값은 720시간(30일)입니다.
validHours와 dueDate 중 하나만 사용할 수 있습니다.
dueDate string
입금 기한입니다. 현재 시간을 기준으로 720시간(30일) 이내의 특정 시점으로 입금 기한을 직접 설정하고 싶을 때 사용합니다. 720시간 이후로 기한을 설정하면 에러가 발생합니다.
ISO 8601 형식인 YYYY-MM-DDThh:mm:ss를 사용합니다.
validHours와 dueDate 중 하나만 사용해야 합니다.
customerMobilePhone string
고객의 휴대폰 번호입니다. 가상계좌 입금 안내가 전송되는 번호입니다.
showCustomerMobilePhone boolean
결제창에서 휴대폰 번호 입력 필드를 보여줄 지 여부입니다. false를 넘기면 가상계좌 결제창에서 휴대폰 번호 입력 필드를 보여주지 않습니다. 기본값은 true 입니다.
cashReceipt object
현금영수증 발급 정보를 담는 객체입니다.
- type string
  현금영수증 발급 용도입니다. 소득공제, 지출증빙, 미발행 중 하나입니다. 소득공제, 지출증빙을 넣으면 해당 용도가 선택된 상태로 결제창이 열립니다. 선택된 용도는 고객이 결제창에서 바꿀 수 있습니다.
useEscrow boolean
에스크로 사용 여부입니다. 값을 주지 않으면 결제창에서 고객이 직접 에스크로 결제 여부를 선택합니다.
escrowProducts array
각 상품의 상세 정보를 담는 배열입니다.
예를 들어 사용자가 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다. 에스크로 결제를 사용할 때만 필요한 파라미터입니다.
id string
상품의 ID입니다. 이 값은 유니크해야 합니다.
name string
상품 이름입니다.
code string
상점에서 사용하는 상품 관리 코드입니다.
unitPrice number
상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격입니다.
quantity number
상품 구매 수량입니다.
refundReceiveAccount object
가상계좌로 결제했을 때 고객에게 환불해 줄 계좌 정보입니다. 결제 승인을 요청한 뒤 돌아온 응답 객체에서 이 정보를 저장해서 사용할 수 있습니다. 응답 정보는 결제창 세션이 유효한 30분 동안에만 조회할 수 있습니다.
bankCode string
고객 환불 계좌의 은행 코드입니다. 최대 길이는 20자입니다. 은행 코드를 참고하세요.
accountNumber string
고객 환불 계좌의 계좌 번호 입니다. 최대 길이는 20자입니다.
holderName string
고객 환불 계좌의 예금주입니다. 최대 길이는 60자입니다.

requestPayment(`계좌이체`, 결제 정보)

계좌이체 결제창을 호출하는 메서드입니다. 첫 번째 파라미터에는 계좌이체/TRANSFER, 두 번째 파라미터에는 결제 정보가 들어갑니다.

tossPayments.requestPayment('계좌이체', { // 결제수단 파라미터
  // 결제 정보 파라미터
  amount: 15000,
  orderId: '',
  orderName: '토스 티셔츠 외 2건',
  successUrl: 'http://localhost:8080/success',
  failUrl: 'http://localhost:8080/fail',
})

JavaScript

amount 필수 · number
결제되는 금액입니다.
orderId 필수 · string
주문 ID입니다. 충분히 무작위한 값을 직접 생성해서 사용하세요. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
orderName 필수 · string
주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.
successUrl 필수 · string
결제가 성공하면 리다이렉트되는 URL입니다. 결제 승인 처리에 필요한 값들이 쿼리 파라미터로 함께 전달됩니다. 반드시 오리진을 포함해야 합니다. 예를 들면 https://www.example.com/success와 같은 형태입니다.
failUrl 필수 · string
결제가 실패하면 리다이렉트되는 URL입니다. 에러 코드 및 에러 메시지가 쿼리 파라미터로 함께 전송됩니다. 반드시 오리진을 포함해야 합니다.
windowTarget string
브라우저에서 결제창이 열리는 프레임을 지정합니다. self, iframe 중 하나입니다.
값을 넣지 않으면 iframe에서 결제창이 열립니다. 현재창에서 결제창으로 이동시키는 방식을 사용하려면 값을 self로 지정하세요.
* 모바일 웹에서는 windowTarget 값과 상관없이 항상 현재창에서 결제창으로 이동합니다.
customerName string
고객의 이름입니다. 최대 길이는 100자입니다.
customerEmail string
고객의 이메일 주소입니다. 최대 길이는 100자입니다.
taxFreeAmount number
결제 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.
*면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.
taxExemptionAmount integer
결제 금액 중 과세 제외 금액(컵 보증금 등)입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다. 카드 결제 또는 간편결제로 계좌이체할 때 사용하세요.
* 과세 제외 금액이 있는 카드 결제는 부분 취소가 안 됩니다.
cultureExpense boolean
문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다.
cashReceipt object
현금영수증 발급 정보를 담는 객체입니다.
- type string
  현금영수증 발급 용도입니다. 소득공제, 지출증빙, 미발행 중 하나입니다. 소득공제, 지출증빙을 넣으면 해당 용도가 선택된 상태로 결제창이 열립니다. 선택된 용도는 고객이 결제창에서 바꿀 수 있습니다.
useEscrow boolean
에스크로 사용 여부입니다. 값을 주지 않으면 결제창에서 고객이 직접 에스크로 결제 여부를 선택합니다.
escrowProducts array
각 상품의 상세 정보 객체를 담는 배열입니다.
예를 들어 사용자가 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다. 에스크로 결제를 사용할 때만 필요한 파라미터입니다.
- id string
  상품의 ID입니다. 이 값은 유니크해야 합니다.
- name string
  상품 이름입니다.
- code string
  상점에서 사용하는 상품 관리 코드입니다.
- unitPrice number
  상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격입니다.
- quantity number
  상품 구매 수량입니다.

requestPayment(`휴대폰`, 결제 정보)

휴대폰 결제창을 호출하는 메서드입니다. 첫 번째 파라미터에는 휴대폰/MOBILE_PHONE, 두 번째 파라미터에는 결제 정보가 들어갑니다.

tossPayments.requestPayment('휴대폰', { // 결제수단 파라미터
  // 결제 정보 파라미터
  amount: 15000,
  orderId: '',
  orderName: '토스 티셔츠 외 2건',
  customerName: '박토스',
  successUrl: 'http://localhost:8080/success',
  failUrl: 'http://localhost:8080/fail',
})

JavaScript

결제 정보

amount 필수 · number
결제되는 금액입니다.
orderId 필수 · string
주문 ID입니다. 충분히 무작위한 값을 직접 생성해서 사용하세요. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
orderName 필수 · string
주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.
successUrl 필수 · string
결제가 성공하면 리다이렉트되는 URL입니다. 결제 승인 처리에 필요한 값들이 쿼리 파라미터로 함께 전달됩니다. 반드시 오리진을 포함해야 합니다. 예를 들면 https://www.example.com/success와 같은 형태입니다.
failUrl 필수 · string
결제가 실패하면 리다이렉트되는 URL입니다. 에러 코드 및 에러 메시지가 쿼리 파라미터로 함께 전송됩니다. 반드시 오리진을 포함해야 합니다.
windowTarget string
브라우저에서 결제창이 열리는 프레임을 지정합니다. self, iframe 중 하나입니다.
값을 넣지 않으면 iframe에서 결제창이 열립니다. 현재창에서 결제창으로 이동시키는 방식을 사용하려면 값을 self로 지정하세요.
* 모바일 웹에서는 windowTarget 값과 상관없이 항상 현재창에서 결제창으로 이동합니다.
customerName string
고객의 이름입니다. 최대 길이는 100자입니다.
customerEmail string
고객의 이메일 주소입니다. 최대 길이는 100자입니다.
taxFreeAmount number
결제 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.
* 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.
mobileCarrier array
결제창에서 선택할 수 있는 통신사를 제한합니다. 배열에 통신사 코드를 추가하면 해당 통신사 코드만 선택할 수 있는 결제창이 뜹니다.
값을 넣지 않으면 모든 통신사 코드를 선택할 수 있는 결제창이 뜹니다. 통신사 코드를 참고하세요.

requestPayment(`상품권`, 결제 정보)

상품권 결제창을 호출하는 메서드입니다. 첫 번째 파라미터에는 문화상품권/CULTURE_GIFT_CERTIFICATE, 도서문화상품권/BOOK_GIFT_CERTIFICATE, 게임문화상품권/GAME_GIFT_CERTIFICATE 중 하나를 설정하세요. 두 번째 파라미터에는 결제 정보가 들어갑니다.

tossPayments.requestPayment('도서문화상품권', { // 결제수단 파라미터
  // 결제 정보 파라미터
  amount: 15000,
  orderId: '',
  orderName: '토스 티셔츠 외 2건',
  customerName: '박토스',
  successUrl: 'http://localhost:8080/success',
  failUrl: 'http://localhost:8080/fail',
})

JavaScript

결제 정보

amount 필수 · number
결제되는 금액입니다.
orderId 필수 · string
주문 ID입니다. 충분히 무작위한 값을 직접 생성해서 사용하세요. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
orderName 필수 · string
주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.
successUrl 필수 · string
결제가 성공하면 리다이렉트되는 URL입니다. 결제 승인 처리에 필요한 값들이 쿼리 파라미터로 함께 전달됩니다. 반드시 오리진을 포함해야 합니다. 예를 들면 https://www.example.com/success와 같은 형태입니다.
failUrl 필수 · string
결제가 실패하면 리다이렉트되는 URL입니다. 에러 코드 및 에러 메시지가 쿼리 파라미터로 함께 전송됩니다. 반드시 오리진을 포함해야 합니다.
windowTarget string
브라우저에서 결제창이 열리는 프레임을 지정합니다. self, iframe 중 하나입니다.
값을 넣지 않으면 iframe에서 결제창이 열립니다. 현재창에서 결제창으로 이동시키는 방식을 사용하려면 값을 self로 지정하세요.
* 모바일 웹에서는 windowTarget 값과 상관없이 항상 현재창에서 결제창으로 이동합니다.
customerName string
고객의 이름입니다. 최대 길이는 100자입니다.
customerEmail string
고객의 이메일 주소입니다. 최대 길이는 100자입니다.
taxFreeAmount number
결제 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.
*면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.

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

자동결제 등록창을 호출하는 메서드입니다. 카드를 등록한 뒤 상점에서 원하는 시점에 자동으로 결제하는 카드 자동결제를 연동할 때 사용합니다.

첫 번째 파라미터에는 카드/CARD, 두 번째 파라미터에는 결제 정보가 들어갑니다. 자동결제는 카드 결제만 지원합니다.

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

JavaScript

결제 정보

customerKey 필수 · string
고객 ID입니다. 충분히 무작위한 값을 직접 생성해서 사용하세요. 빌링키와 연결됩니다. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @로 이루어진 최소 2자 이상 최대 300자 이하의 문자열입니다.
successUrl 필수 · string
결제가 성공하면 리다이렉트되는 URL입니다. 결제 승인 처리에 필요한 값들이 쿼리 파라미터로 함께 전달됩니다. 반드시 오리진을 포함해야 합니다. 예를 들면 https://www.example.com/success와 같은 형태입니다.
failUrl 필수 · string
결제가 실패하면 리다이렉트되는 URL입니다. 에러 코드 및 에러 메시지가 쿼리 파라미터로 함께 전송됩니다. 반드시 오리진을 포함해야 합니다.
customerName string
고객의 이름입니다. 최대 길이는 100자입니다.
customerEmail string
고객의 이메일 주소입니다. 최대 길이는 100자입니다.
windowTarget string
브라우저에서 결제창이 열리는 프레임을 지정합니다. self, iframe 중 하나입니다.
값을 넣지 않으면 iframe에서 결제창이 열립니다. 현재창에서 결제창으로 이동시키는 방식을 사용하려면 값을 self로 지정하세요.
* 모바일 웹에서는 windowTarget 값과 상관없이 항상 현재창에서 결제창으로 이동합니다.

cancelPayment()

cancelPayment()를 실행하면 열려있는 iframe 결제창이 닫히고 진행 중인 결제는 취소됩니다.

React 또는 Vue.js로 SPA(Single Page Application) 사이트를 구현했을 때 사용합니다. 데스크탑 브라우저에서 페이지를 전환해도 결제창 iframe이 남아 있다면 cancelPayment()를 실행하세요.

// React를 사용하는 경우
useEffect(() => {
  return () => {
    tossPayments.cancelPayment();
  };
}, [tossPayments]);

JavaScript

* 모바일 웹에서는 아무 동작도 실행되지 않습니다.

모바일 SDK

모바일 환경에서 사용할 수 있는 결제창 SDK입니다.

FlutterFlutter 앱에 결제창을 연동하세요

AndroidAndroid 앱에 결제창을 연동하세요

iOSiOS 앱에 결제창을 연동하세요

결제 요청 응답 처리

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

리다이렉트 URL로 처리하기

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

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

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

주문서

tossPayments.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' 처리하기
  }
})

JavaScript

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

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

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

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

Promise로 처리하기

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

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

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

예시

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

JavaScript

응답 데이터

성공 응답

paymentKey string
결제를 식별하는 키 값입니다. 토스페이먼츠에서 발급합니다. 결제 승인, 결제 조회, 결제 취소 등 운영에 필요한 값입니다.
orderId string
주문 ID입니다. 결제 요청에 보낸 값입니다.
amount number
결제 금액입니다. 결제 요청에 보낸 결제 금액과 같은지 반드시 확인해보세요. 클라이언트에서 결제 금액을 조작해 승인하는 행위를 방지할 수 있습니다. 만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요. 적립금이나 쿠폰이 적용된 금액이 맞는지도 확인해보세요.

실패 응답

code string
에러 코드입니다. 에러 목록을 확인하세요.
message string
에러 메시지입니다.
orderId string
주문 ID입니다. 결제 요청에 담아 보낸 값입니다.

.css-p1o082{width:calc(0.8em + 8px);height:0.8em;position:absolute;top:calc(50% - 0.4em);left:calc(-0.8em - 8px);padding-right:8px;opacity:0;-webkit-transition:opacity 0.2s ease-in-out;-webkit-transition:opacity 0.2s ease-in-out;transition:opacity 0.2s ease-in-out;}결제창 JavaScript SDK

초기화 파라미터

메서드

requestPayment(카드, 결제 정보)

결제 정보

requestPayment(가상계좌, 결제 정보)

결제 정보

requestPayment(계좌이체, 결제 정보)

requestPayment(휴대폰, 결제 정보)

결제 정보

requestPayment(상품권, 결제 정보)

결제 정보

requestBillingAuth(카드, 결제 정보)

결제 정보

cancelPayment()

모바일 SDK

결제 요청 응답 처리

리다이렉트 URL로 처리하기

Promise로 처리하기

응답 데이터

성공 응답

실패 응답

결제창 JavaScript SDK

requestPayment(`카드`, 결제 정보)

requestPayment(`가상계좌`, 결제 정보)

requestPayment(`계좌이체`, 결제 정보)

requestPayment(`휴대폰`, 결제 정보)

requestPayment(`상품권`, 결제 정보)

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