결제창 JavaScript 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 객체를 반환합니다.
카드 결제창을 호출하는 메서드입니다. 첫 번째 파라미터에는 카드
/CARD
, 두 번째 파라미터에는 결제 정보가 들어갑니다.
tossPayments.requestPayment('카드', {
amount: 15000,
orderId: '',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: 'http://localhost:8080/success',
failUrl: 'http://localhost:8080/fail',
})
- 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://
같은 형태입니다.
가상계좌 결제창을 호출하는 메서드입니다. 첫 번째 파라미터에는 가상계좌
/VIRTUAL_ACCOUNT
, 두 번째 파라미터에는 결제 정보가 들어갑니다.
tossPayments.requestPayment('가상계좌', { // 결제수단 파라미터
// 결제 정보 파라미터
amount: 15000,
orderId: '',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: 'http://localhost:8080/success',
failUrl: 'http://localhost:8080/fail',
validHours: 24,
cashReceipt: {
type: '소득공제',
},
})
- 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
현금영수증 발급 용도입니다.
소득공제
,지출증빙
,미발행
중 하나입니다.소득공제
,지출증빙
을 넣으면 해당 용도가 선택된 상태로 결제창이 열립니다. 선택된 용도는 고객이 결제창에서 바꿀 수 있습니다.
- 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자입니다.
계좌이체 결제창을 호출하는 메서드입니다. 첫 번째 파라미터에는 계좌이체
/TRANSFER
, 두 번째 파라미터에는 결제 정보가 들어갑니다.
tossPayments.requestPayment('계좌이체', { // 결제수단 파라미터
// 결제 정보 파라미터
amount: 15000,
orderId: '',
orderName: '토스 티셔츠 외 2건',
successUrl: 'http://localhost:8080/success',
failUrl: 'http://localhost:8080/fail',
})
- 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
현금영수증 발급 용도입니다.
소득공제
,지출증빙
,미발행
중 하나입니다.소득공제
,지출증빙
을 넣으면 해당 용도가 선택된 상태로 결제창이 열립니다. 선택된 용도는 고객이 결제창에서 바꿀 수 있습니다.
- type string
- useEscrow boolean
에스크로 사용 여부입니다. 값을 주지 않으면 결제창에서 고객이 직접 에스크로 결제 여부를 선택합니다.
- escrowProducts array
각 상품의 상세 정보 객체를 담는 배열입니다.
예를 들어 사용자가 세 가지 종류의 상품을 구매했다면 길이가 3인 배열이어야 합니다. 에스크로 결제를 사용할 때만 필요한 파라미터입니다.
- id string
상품의 ID입니다. 이 값은 유니크해야 합니다.
- name string
상품 이름입니다.
- code string
상점에서 사용하는 상품 관리 코드입니다.
- unitPrice number
상품의 가격입니다. 전체를 합한 가격이 아닌 상품의 개당 가격입니다.
- quantity number
상품 구매 수량입니다.
- id string
휴대폰 결제창을 호출하는 메서드입니다. 첫 번째 파라미터에는 휴대폰
/MOBILE_PHONE
, 두 번째 파라미터에는 결제 정보가 들어갑니다.
tossPayments.requestPayment('휴대폰', { // 결제수단 파라미터
// 결제 정보 파라미터
amount: 15000,
orderId: '',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: 'http://localhost:8080/success',
failUrl: 'http://localhost:8080/fail',
})
- 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
결제창에서 선택할 수 있는 통신사를 제한합니다. 배열에 통신사 코드를 추가하면 해당 통신사 코드만 선택할 수 있는 결제창이 뜹니다.
값을 넣지 않으면 모든 통신사 코드를 선택할 수 있는 결제창이 뜹니다. 통신사 코드를 참고하세요.
상품권 결제창을 호출하는 메서드입니다. 첫 번째 파라미터에는 문화상품권
/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',
})
- 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
으로 설정됩니다.*면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.
자동결제 등록창을 호출하는 메서드입니다. 카드를 등록한 뒤 상점에서 원하는 시점에 자동으로 결제하는 카드 자동결제를 연동할 때 사용합니다.
첫 번째 파라미터에는 카드
/CARD
, 두 번째 파라미터에는 결제 정보가 들어갑니다. 자동결제는 카드 결제만 지원합니다.
tossPayments.requestBillingAuth('카드', {
customerKey: '',
successUrl: 'http://localhost:8080/success',
failUrl: 'http://localhost:8080/fail',
})
- 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()
를 실행하면 열려있는 iframe 결제창이 닫히고 진행 중인 결제는 취소됩니다.
React 또는 Vue.js로 SPA(Single Page Application) 사이트를 구현했을 때 사용합니다. 데스크탑 브라우저에서 페이지를 전환해도 결제창 iframe이 남아 있다면 cancelPayment()
를 실행하세요.
// React를 사용하는 경우
useEffect(() => {
return () => {
tossPayments.cancelPayment();
};
}, [tossPayments]);
* 모바일 웹에서는 아무 동작도 실행되지 않습니다.
모바일 환경에서 사용할 수 있는 결제창 SDK입니다.
requestPayment()
메서드 응답은 리다이렉트 URL 또는 Promise로 처리할 수 있습니다.
✔️ 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' 처리하기
}
})
✅ 결제 요청 성공: 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}
✔️ 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') {
// 유효하지 않은 카드 코드에 대한 에러 처리
}
});
- paymentKey string
결제를 식별하는 키 값입니다. 토스페이먼츠에서 발급합니다. 결제 승인, 결제 조회, 결제 취소 등 운영에 필요한 값입니다.
- orderId string
주문 ID입니다. 결제 요청에 보낸 값입니다.
- amount number
결제 금액입니다. 결제 요청에 보낸 결제 금액과 같은지 반드시 확인해보세요. 클라이언트에서 결제 금액을 조작해 승인하는 행위를 방지할 수 있습니다. 만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요. 적립금이나 쿠폰이 적용된 금액이 맞는지도 확인해보세요.
- code string
에러 코드입니다. 에러 목록을 확인하세요.
- message string
에러 메시지입니다.
- orderId string
주문 ID입니다. 결제 요청에 담아 보낸 값입니다.