브랜드페이 JavaScript SDK

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

SDK 설치 및 초기화

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

<head>
  <meta charset="utf-8" />
  <title>브랜드페이로 결제하기</title>
  <!-- 1. 스크립트 추가 -->
  <script src="https://js.tosspayments.com/v1/brandpay"></script>
</head>
<script>
  var clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq' // 테스트용 클라이언트 키
  var customerKey = '{CUSTOMER_KEY}' // 내 상점에서 고객을 구분하기 위해 발급한 고객의 고유 ID

  // 2. 브랜드페이 객체 생성
  var brandpay = BrandPay(clientKey, customerKey, {
    redirectUrl: 'http://example.com',
    ui: {
      buttonStyle: 'full',
      highlightColor: '#26C2E3',
      labels: {
        oneTouchPay: '내 상점 원터치결제',
      },
    },
  })
</script>

초기화 파라미터

clientKey 필수 · string
클라이언트 키는 브라우저에서 결제창을 연동할 때 사용합니다. 토스페이먼츠에서 발급합니다. API 키 페이지에서 결제위젯 MID로 발급된 키 값을 사용하세요.
customerKey 필수 · string
고객 ID입니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용할 수 있어 자동 증가하는 숫자는 안전하지 않습니다. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 를 최소 1개 이상 포함한 최소 2자 이상 최대 50자 이하의 문자열이어야 합니다.
options object
인증에 필수인 리다이렉트 URL, 선택적으로 적용할 수 있는 UI 옵션으로 이루어진 객체입니다.

redirectUrl string
리다이렉트 URL에는 Access Token 발급 과정에 필요한 값이 돌아옵니다. Access Token은 브랜드페이 고객을 식별하고 고객의 결제 권한을 증명합니다. 값을 넣지 않으면 브랜드페이 페이지에 최초로 등록한 리다이렉트 URL이 기본값으로 들어갑니다.
* 브랜드페이 페이지에 두 개 이상의 리다이렉트 URL을 등록한 상점은 각 도메인에 맞는 redirectUrl 값을 필수로 추가하세요.
ui string
UI 커스터마이징 옵션을 담은 객체입니다. 각 파라미터 옵션에 따라 달라지는 결제창 UI는 아래 이미지를 참고하세요.

buttonStyle string
버튼 스타일입니다. 값을 넣지 않으면 기본값인 default로 설정됩니다.
default로 설정하면 모서리가 둥글고 주변에 여백을 가진 버튼을 사용할 수 있고, full로 설정하면 하단 영역이 전부 채워지는 형태의 버튼을 사용할 수 있습니다.
highlightColor string
UI의 메인 색상입니다. 값을 넣지 않으면 기본 색상인 #3182f6로 설정됩니다. 웹에서 사용할 수 있는 색상 코드 형식을 모두 사용할 수 있습니다.

navigationBar object
화면 뒤로 가기 기능을 제공하는 내비게이션 바 설정 정보입니다.
visible boolean
내비게이션 바 사용 여부입니다. 값을 넣지 않으면 기본값인 true로 설정됩니다. 내비게이션 바를 사용하지 않으려면 false로 설정해야 합니다.
paddingTop number
내비게이션 바 위쪽에 설정할 여백 값입니다. 값의 단위는 px입니다.

labels object
UI에 사용되는 커스텀 텍스트를 모아둔 객체입니다.
oneTouchPay string
UI에 표시되는 원터치결제를 대신해 사용할 텍스트입니다. 값을 넣지 않으면 원터치결제로 표시됩니다.

windowTarget string
브랜드페이 창을 여는 방법입니다. iframe, popup 중 하나입니다. 기본값은 iframe입니다. 모바일 환경에서는 popup을 사용할 수 없습니다.

UI 파라미터 옵션에 따라 달라지는 결제창 화면 예시

메서드

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

휴대폰 본인 인증이 진행된 후에 메서드를 사용할 수 있습니다. 만약 휴대폰 본인 인증이 완료되지 않은 상태에서 메서드를 실행하면 휴대폰 본인 인증 과정을 먼저 거치게 됩니다.

setupPassword()

결제할 때 사용할 비밀번호를 설정할 수 있는 메서드입니다. 비밀번호 등록・변경이 완료되면 Promise가 resolve됩니다.

brandpay.setupPassword().catch(function (error) {
  if (error.code === 'USER_CANCEL') {
    // 사용자가 창을 닫아 취소한 경우에 대한 처리
  }
})

JavaScript

getPaymentMethods()

등록되어 있는 결제수단을 조회하는 메서드입니다. 조회가 성공했을 때 Promise가 resolve되고 고객의 결제수단 정보(BrandpayMethodResponse)가 반환됩니다.

brandpay
  .getPaymentMethods()
  .then(function (methods) {
    // 성공 처리
  })
  .catch(function (error) {
    if (error.code === 'USER_CANCEL') {
      // 사용자가 결제창을 닫은 경우 에러 처리
    }
  })

JavaScript

BrandpayMethodResponse

selectedMethodId string
가장 최근에 등록했거나 사용한 결제수단의 id 값입니다.
cards array
등록된 카드 정보입니다.
id string
결제수단의 아이디입니다.
cardName string
카드 이름입니다.
alias string
고객이 직접 설정한 해당 결제수단의 별명입니다.
cardNumber string
카드 번호입니다.
cardCompany string
카드 발급사 코드입니다. 카드사 코드를 참고하세요.
issueCompany string
카드 발급사 코드입니다. 카드사 코드를 참고하세요.
companyCode string
카드 발급사 숫자 코드입니다. 카드사 코드를 참고하세요.
acquirerCode string
카드 매입사 숫자 코드입니다. 카드사 코드를 참고하세요.
issuerCode string
카드 발급사 숫자 코드입니다. 카드사 코드를 참고하세요.
ownerType string
카드의 소유자 타입입니다. 개인, 법인 중 하나입니다.
cardType string
카드 종류입니다. 신용, 체크, 기프트 중 하나입니다.
installmentMinimumAmount string
할부가 가능한 최소 금액 정보입니다. 이 금액과 고객이 결제할 금액을 비교해서 할부 선택 UI를 보여줄 지 결정할 수 있습니다.
registeredAt string
결제수단을 등록한 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다. (e.g. 2022-01-01T00:00:00+09:00)
status string
결제수단 활성화 여부를 나타냅니다. 결제수단을 조회할 때는 이 값이 ENABLED인 결제수단만 돌아옵니다. 결제수단을 삭제하면 이 값이 DISABLED로 변경됩니다.
- ENABLED: 결제수단이 등록되어 사용할 수 있는 상태
- DISABLED: 결제수단이 삭제되어 사용할 수 없는 상태
isAvailable boolean
결제수단 사용 가능 여부입니다.
icon string
카드사・은행 아이콘입니다. 예를 들어 icn-bank-square-hyundaicard는 현대카드 아이콘 코드입니다. icn-bank-square-에 카드사・은행 이름이 조합되어 있습니다.
iconUrl string
카드사・은행 아이콘 이미지 URL입니다. 이 값을 이미지 주소로 사용하면 화면에 카드사・은행 아이콘을 보여줄 수 있습니다.
icons string
카드사・은행 아이콘 이름, URL입니다.
- fill: 배경이 채워진 아이콘입니다.
- normal: 배경이 없는 아이콘입니다.
- square: 직사각형 아이콘입니다.
color string
아이콘의 색상입니다. 아이콘 이미지와 함께 결제수단 UI를 직접 만들 때 사용할 수 있습니다.
- background: 아이콘의 배경색입니다.
- text: 아이콘의 텍스트 색입니다.
cardImgUrl string
카드 실물 이미지 URL입니다. 이 값을 이미지 주소로 사용하면 화면에 카드 실물 이미지를 보여줄 수 있습니다.
cardProductCode string
PLCC 상품을 구분하는 코드입니다. 카드사에서 발급합니다.
accounts array
등록된 계좌 정보입니다.
id string
결제수단의 아이디입니다.
type string
계좌 유형입니다. 일반 출금 계좌를 등록하면 WITHDRAW 값이 돌아옵니다.
accountName string
계좌 이름입니다.
alias string
고객이 직접 설정한 해당 결제수단의 별명입니다.
bank string
은행 코드입니다. 단위농협과 홍콩상하이은행을 제외하고 지원합니다. 은행 코드를 참고하세요.
bankCode string
은행 숫자 코드입니다. 단위농협과 홍콩상하이은행을 제외하고 지원합니다. 은행 코드를 참고하세요.
accountNumber string
계좌번호입니다.
registeredAt string
결제수단을 등록한 날짜와 시간 정보입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다. (e.g. 2022-01-01T00:00:00+09:00)
status string
결제수단 활성화 여부를 나타냅니다. 결제수단을 조회할 때는 이 값이 ENABLED인 결제수단만 돌아옵니다. 결제수단을 삭제하면 이 값이 DISABLED로 변경됩니다.
- ENABLED: 결제수단이 등록되어 사용할 수 있는 상태
- DISABLED: 결제수단이 삭제되어 사용할 수 없는 상태
isAvailable boolean
결제수단 사용 가능 여부입니다.
icon string
카드사・은행 아이콘입니다. 예를 들어 icn-bank-square-hyundaicard는 현대카드 아이콘 코드입니다. icn-bank-square-에 카드사・은행 이름이 조합되어 있습니다.
iconUrl string
카드사・은행 아이콘 이미지 URL입니다. 이 값을 이미지 주소로 사용하면 화면에 카드사・은행 아이콘을 보여줄 수 있습니다.
icons string
은행 아이콘 이름, URL입니다.
- fill: 배경이 채워진 아이콘입니다.
- normal: 배경이 없는 아이콘입니다.
- square: 직사각형 아이콘입니다.
color string
아이콘의 색상입니다. 아이콘 이미지와 함께 결제수단 UI를 직접 만들 때 사용할 수 있습니다.
- background: 아이콘의 배경색입니다.
- text: 아이콘의 텍스트 색입니다.

addPaymentMethod('카드'|'계좌')

결제수단을 등록할 수 있는 메서드입니다. 카드, 계좌 중 등록할 결제수단을 파라미터로 추가하면 바로 해당 결제수단 등록 창으로 연결됩니다. 파라미터 없이 실행하면 결제수단을 선택하는 창으로 연결됩니다.

결제수단이 등록되면 Promise가 돌아오고 then블록에서 고객이 등록한 모든 결제수단을 확인할 수 있습니다.

brandpay
  .addPaymentMethod('카드')
  .then(function (methods) {
    // 성공 처리
  })
  .catch(function (error) {
    if (error.code === 'USER_CANCEL') {
      // 사용자가 결제창을 닫은 경우 에러 처리
    }
  })

JavaScript

응답

newCustomerToken string
토스페이먼츠에서 사용하는 고객의 인증 토큰입니다.
result object
고객의 결제 수단 정보를 담은 BrandpayMethodResponse 객체입니다.

requestPayment(결제 정보)

브랜드페이 결제창을 띄우고 결제를 요청하는 메서드입니다. 결제 요청의 응답을 처리하는 방법을 알아보세요.

brandpay
  .requestPayment({
    amount: 15000,
    orderId: '',
    orderName: '토스 티셔츠 외 2건',
    customerName: '박토스',
    customerEmail: 'customer@example.com',
  })
  .then(function (data) {
    // 결제 요청 성공 처리
  })
  .catch(function (error) {
    if (error.code === 'USER_CANCEL') {
      // 사용자가 창을 닫아 취소한 경우에 대한 처리
    }
  })

JavaScript

결제 정보

amount 필수 · number
결제되는 금액입니다.
orderId 필수 · string
주문을 구분하는 ID입니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요.
orderName 필수 · string
주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다.
successUrl string
결제가 성공하면 리다이렉트되는 URL입니다. 결제 승인 처리에 필요한 값들이 쿼리 파라미터로 함께 전달됩니다. 반드시 오리진을 포함해야 합니다. 예를 들면 https://www.example.com/success와 같은 형태입니다. 리다이렉트 URL 방식으로 결제 요청을 처리하고 싶을 때 추가해주세요.
failUrl string
결제가 실패하면 리다이렉트되는 URL입니다. 에러 코드 및 에러 메시지가 쿼리 파라미터로 함께 전송됩니다. 반드시 오리진을 포함해야 합니다.
methodId string
결제수단 ID 입니다. 등록되어 있는 결제수단 중 하나를 지정해서 바로 결제하고 싶을 때 사용합니다.
customerEmail string
고객의 이메일 주소입니다. 결제 결과를 알려줄 때 사용합니다. 최대 길이는 100자입니다.
shippingAddress string
고객의 배송지 주소입니다. 부정거래탐지시스템(FDS, Fraud Detection System, 거래 정보와 고객 정보, 평소 거래 패턴 등을 분석해서 의심되는 전자금융거래를 탐지하고 차단하는 기술)에 사용할 수 있습니다.
taxFreeAmount string
결제할 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.
* 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.
cultureExpense boolean
문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다. 결제수단이 계좌일 때만 설정하세요.
cardInstallmentPlan number
신용 카드의 할부 개월 수입니다. 값을 넣으면 해당 할부 개월 수로 결제가 진행됩니다.
- 2부터 12사이의 값을 사용할 수 있고, 0이 들어가면 할부가 아닌 일시불로 결제됩니다.
- 결제 금액(amount)이 5만원 이상일 때만 할부가 적용됩니다.
useCardPoint boolean
카드로 결제할 때 설정하는 카드사 포인트 사용 여부입니다. 값을 주지 않거나 값이 false라면 사용자가 카드사 포인트 사용 여부를 결정할 수 있습니다. 이 값을 true로 주면 카드사 포인트 사용이 체크된 상태로 결제창이 열립니다.
* 추가 계약 후 사용할 수 있습니다. 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.
discountCode string
카드사 즉시 할인 코드입니다.
카드혜택 조회 API로 적용할 수 있는 할인 코드의 목록을 조회할 수 있습니다.
cashReceipt string
계좌로 결제할 때 현금영수증 발급 정보를 담는 객체입니다.
type 필수 · string
현금영수증의 종류입니다. 소득공제, 지출증빙, 미발행 중 하나입니다.
registrationNumberType string
현금영수증 번호 타입입니다. 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호 중 하나를 선택할 수 있습니다.
- MOBILE: 휴대폰 번호
- BUSINESS_REGISTRATION: 사업자등록번호
- CASH_RECEIPT_CARD: 현금영수증 카드 번호
registrationNumber string
현금영수증 발급에 필요한 소비자 인증수단입니다. 현금영수증을 발급한 주체를 식별합니다. 현금영수증 종류에 따라 휴대폰 번호, 주민등록번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다.

openSettings()

브랜드페이에서 사용하는 결제수단, 비밀번호, 원터치결제 사용을 관리하는 결제 관리창을 열 수 있습니다.

brandpay.openSettings().catch(function (error) {
  if (error.code === 'USER_CANCEL') {
    // 사용자가 창을 닫아 취소한 경우에 대한 처리
  }
})

JavaScript

setupOneTouchPay()

원터치페이 설정창을 열어서 원터치페이 사용 여부를 설정할 수 있습니다. 원터치페이는 결제할 때 비밀번호 입력없이 바로 결제할 수 있는 기능입니다.

메서드를 실행하면 Promise가 돌아오고, 원터치페이 설정이 완료되어 창이 닫히면 Promise가 fulfilled 상태로 변경됩니다.

brandpay.setupOneTouchPay().catch(function (error) {
  if (error.code === 'USER_CANCEL') {
    // 사용자가 창을 닫아 취소한 경우에 대한 처리
  }
})

JavaScript

toggleOneTouchPay()

원터치페이 설정창에 진입하지 않고 바로 끄거나 켤 때 사용합니다. 원터치페이는 결제할 때 비밀번호 입력없이 바로 결제할 수 있는 기능입니다. 설정이 꺼진 상태에서 켜진 상태로 바뀔 때는 비밀번호 입력창이 열리고, 비밀번호를 입력하면 설정이 완료됩니다. 켜진 상태에서 꺼진 상태로 바꿀 때는 바로 꺼진 상태로 설정이 변경됩니다.

메서드를 실행하면 Promise가 돌아옵니다. 원터치페이 설정을 켤 때는 비밀번호 입력 후 then 블록에서 { isEnabled: true }가 돌아온 것을 확인할 수 있습니다. 만약 원터치페이 설정을 끄면 { isEnabled: false }가 돌아옵니다.

brandpay.toggleOneTouchPay().catch(function (error) {
  if (error.code === 'USER_CANCEL') {
    // 사용자가 창을 닫아 취소한 경우에 대한 처리
  }
})

JavaScript

isOneTouchPayEnabled()

사용자의 원터치페이 설정 상태를 확인할 때 사용합니다. 원터치페이는 결제할 때 비밀번호 입력없이 바로 결제할 수 있는 기능입니다.

메서드를 실행하면 Promise가 돌아오고, then 블록에서 원터치페이 설정 여부를 알 수 있습니다. 원터치페이가 설정되어 있다면 true, 설정되어 있지 않으면 false가 돌아옵니다.

brandpay.isOneTouchPayEnabled().catch(function (error) {
  if (error.code === 'USER_CANCEL') {
    // 사용자가 창을 닫아 취소한 경우에 대한 처리
  }
})

JavaScript

requestAgreement(약관 항목)

약관 동의 창을 띄우는 메서드입니다.

동의 받을 약관 항목을 파라미터로 추가하세요. 회원가입, 카드, 계좌, 빌링 항목이 있습니다. 고객이 각 서비스를 이용할 때 해당 약관의 동의를 받으세요.

예를 들어 파라미터를 빌링으로 설정하고 메서드를 실행하면 자동결제 약관 동의 창이 열립니다. 고객이 약관에 동의를 하면 Promise가 resolve됩니다.

응답

brandpay
  .requestAgreement('빌링') // 자동결제 선택 약관 동의 호출
  .then(function () {
    // 성공 처리
  })
  .catch(function (error) {
    if (error.code === 'USER_CANCEL') {
      // 사용자가 창을 닫아 취소한 경우에 대한 처리
    }
  })

JavaScript

결제 요청 응답 처리

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

리다이렉트 URL로 처리하기

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

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

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

주문서

brandpay
  .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}&methodId={METHOD_ID}

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

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

Promise로 처리하기

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

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

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

예시

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

실패 응답

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

초기화 파라미터

UI 파라미터 옵션에 따라 달라지는 결제창 화면 예시

메서드

setupPassword()

getPaymentMethods()

BrandpayMethodResponse

addPaymentMethod('카드'|'계좌')

응답

requestPayment(결제 정보)

결제 정보

openSettings()

setupOneTouchPay()

toggleOneTouchPay()

isOneTouchPayEnabled()

requestAgreement(약관 항목)

결제 요청 응답 처리

리다이렉트 URL로 처리하기

Promise로 처리하기

응답 데이터

성공 응답

실패 응답

브랜드페이 JavaScript SDK