브랜드페이 JavaScript SDK

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

• clientKey 필수 · string
  

  클라이언트 키는 브라우저에서 결제창을 연동할 때 사용합니다. 토스페이먼츠에서 발급합니다. API 키 페이지에서 API 개별 연동 키 > 브랜드페이 MID로 발급된 키 값을 사용하세요.

• customerKey 필수 · string
  

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

• options object
  

  인증에 필수인 리다이렉트 URL, 선택적으로 적용할 수 있는 UI 옵션으로 이루어진 객체입니다.

• redirectUrl string
  

  리다이렉트 URL에는 Access Token 발급 과정에 필요한 값이 돌아옵니다. Access Token은 브랜드페이 고객을 식별하고 고객의 결제 권한을 증명합니다. 값을 넣지 않으면 브랜드페이 페이지에 최초로 등록한 리다이렉트 URL이 기본값으로 들어갑니다.

  * 브랜드페이 페이지에 두 개 이상의 리다이렉트 URL을 등록한 상점은 각 도메인에 맞는 redirectUrl 값을 필수로 추가하세요.

• windowTarget string
  

  브라우저에서 브랜드페이창이 열리는 프레임입니다. iframe, popup 중 하나입니다.

  - iframe은 iframe에서 브랜드페이창이 열려요. 기본 값입니다.

  - popup은 팝업에서 브랜드페이 창이 열려요. 모바일 환경에서는 popup을 사용할 수 없습니다.

브랜드페이 JavaScript SDK에서 제공하는 메서드 목록입니다.

브랜드페이 회원은 SDK를 초기화할 때 사용한 customerKey로 구분됩니다. 회원의 결제수단이 등록되지 않은 상태에서 브랜드페이 메서드를 실행하면 결제수단 등록이 먼저 진행됩니다.

결제수단을 등록하는 메서드입니다.

• methodType string
  

  등록하고 싶은 결제수단입니다. 카드, 계좌를 지원합니다. 파라미터 없이 실행하면 계좌와 카드를 모두 등록할 수 있는 창으로 연결됩니다.

결제수단이 등록되면 Promise가 돌아옵니다. Promise는 결제수단 정보가 있는 BrandpayMethodResponse 객체를 반환합니다.

등록된 결제수단을 조회하는 메서드입니다.

결제수단을 조회하면 Promise가 돌아옵니다. Promise는 결제수단 정보가 있는 BrandpayMethodResponse 객체를 반환합니다.

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

• RequestPaymentParameters 필수 · object
  

  결제 정보 파라미터입니다.

• amount 필수 · number
  

  결제되는 금액입니다.

• orderId 필수 · string
  

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

• orderName 필수 · string
  

  구매상품입니다. 예를 들면 생수 외 1건 같은 형식입니다.

• successUrl string
  

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

• failUrl string
  

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

• methodId string
  

  결제수단 ID 입니다. 등록되어 있는 결제수단 중 하나를 지정해서 바로 결제하고 싶을 때 사용합니다.

• customerEmail string
  

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

• metadata object
  

  결제 관련 정보를 추가할 수 있는 객체입니다. 최대 5개의 키-값(key-value) 쌍을 자유롭게 추가해주세요. 키는 [ , ] 를 사용하지 않는 최대 40자의 문자열, 값은 최대 500자의 문자열입니다.

• taxFreeAmount string
  

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

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

• cultureExpense boolean
  

  문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다. 결제수단이 계좌일 때만 설정하세요.

• cardInstallmentPlan number
  

  신용 카드의 할부 개월 수입니다. 값을 넣으면 해당 할부 개월 수로 결제가 진행됩니다.

  • 2부터 12사이의 값을 사용할 수 있고, 0이 들어가면 할부가 아닌 일시불로 결제됩니다.
  • 결제 금액(amount)이 5만원 이상일 때만 할부가 적용됩니다.
• useCardPoint boolean
  

  카드로 결제할 때 설정하는 카드사 포인트 사용 여부입니다. 값을 주지 않거나 값이 false라면 사용자가 카드사 포인트 사용 여부를 결정할 수 있습니다. 이 값을 true로 주면 카드사 포인트 사용이 체크된 상태로 결제창이 열립니다.

  * 추가 계약 후 사용할 수 있습니다. 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

• discountCode string
  

  카드 또는 계좌 즉시 할인 코드입니다.

  카드 프로모션 조회 API, 계좌 프로모션 조회 API로 적용할 수 있는 할인 코드의 목록을 조회할 수 있습니다.

• cashReceipt object
  

  계좌로 결제할 때 현금영수증 발급 정보를 담는 객체입니다.

• type 필수 · string
  

  현금영수증의 종류입니다. 소득공제, 지출증빙, 미발행 중 하나입니다.

• registrationNumberType string
  

  현금영수증 번호 타입입니다. 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호 중 하나를 선택할 수 있습니다.

  • MOBILE: 휴대폰 번호

  • BUSINESS_REGISTRATION: 사업자등록번호

  • CASH_RECEIPT_CARD: 현금영수증 카드 번호

• registrationNumber string
  

  현금영수증 발급에 필요한 소비자 인증수단입니다. 현금영수증을 발급한 주체를 식별합니다. 현금영수증 종류에 따라 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다.

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

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

브랜드페이 결제 관리창을 여는 메서드입니다. 결제수단 관리, 결제 비밀번호 설정, 원터치결제 설정, 이메일 관리 메뉴가 있습니다.

결제 관리창이 열리면 resolve되지 않는 Promise가 반환됩니다.

결제 비밀번호를 변경하는 메서드입니다. 기존 비밀번호를 입력하고 새로운 비밀번호를 설정할 수 있어요. 결제수단이 등록되지 않은 구매자라면 결제수단이 등록됩니다.

비밀번호 등록・변경이 완료되면 resolve되지 않는 Promise가 반환됩니다.

원터치결제 설정창을 여는 메서드입니다. 원터치결제를 끄거나 켤 수 있습니다. 원터치결제를 사용하면 보안 시스템에서 판단한 안전한 거래에서 비밀번호를 누르지 않아도 됩니다.

원터치결제 설정창이 열리면 resolve되지 않는 Promise가 반환됩니다.

원터치결제 설정창에 진입하지 않고 바로 끄거나 켤 때 사용합니다. 원터치결제가 꺼진 상태에서 켤 때는 비밀번호를 입력해야 설정이 완료됩니다. 켜진 상태에서 끌 때는 바로 상태가 변경됩니다.

원터치결제를 사용하면 보안 시스템에서 판단한 안전한 거래에서 비밀번호를 누르지 않아도 됩니다.

원터치결제 설정이 바뀌면 Promise가 resolve되고 다음과 같은 객체를 반환합니다.

• isEnabled: 원터치결제 설정을 켤 때는 true 값이 돌아오고, 원터치결제 설정을 끄면 false 값이 돌아옵니다.

사용자의 원터치결제 설정 상태를 확인할 때 사용합니다. 원터치결제를 사용하면 보안 시스템에서 판단한 안전한 거래에서 비밀번호를 누르지 않아도 됩니다.

원터치결제 설정 상태가 확인되면 Promise가 resolve되고 boolean을 반환합니다. 원터치결제가 설정되어 있다면 true, 설정되어 있지 않으면 false가 돌아옵니다.

약관 동의 창을 띄우는 메서드입니다. 자동결제(빌링)를 연동할 때만 이 메서드를 실행하세요. 회원가입, 카드, 계좌 관련 약관은 최초에 결제수단을 등록할 때 SDK가 자동으로 메서드를 실행합니다.

• termScope string
  

  동의를 받고 싶은 약관 항목입니다. 예를 들어 빌링으로 설정하면 자동결제 약관 동의 창이 열립니다. 카드, 계좌, 회원가입, 빌링을 지원합니다.

구매자가 약관에 동의하면 Promise가 resolve됩니다.

• selectedMethodId string
  

  가장 최근에 등록했거나 사용한 결제수단의 id 값입니다.

• cards array
  

  등록된 카드 정보입니다.

• id string
  

  결제수단의 아이디입니다.

• cardName string
  

  카드 이름입니다.

• alias string
  

  고객이 직접 설정한 해당 결제수단의 별명입니다.

• cardNumber string
  

  카드 번호입니다.

• cardCompany string
  DEPRECATED
  
  

  카드 발급사 코드입니다. 카드사 코드를 참고하세요.

• issueCompany string
  DEPRECATED
  
  

  카드 발급사 코드입니다. 카드사 코드를 참고하세요.

• companyCode string
  DEPRECATED
  
  

  카드 발급사 두 자리 코드입니다. 카드사 코드를 참고하세요.

• 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 object
  

  카드사・은행 아이콘의 이름, URL입니다. 각 아이콘 종류에 name, url 필드가 돌아옵니다.

• normal object
  

  배경이 없는 아이콘의 이름, URL입니다.

• fill object
  

  배경이 채워진 아이콘의 이름, URL입니다.

• square object
  

  직사각형 아이콘의 이름, URL입니다.

• color object
  

  아이콘의 색상입니다. 아이콘 이미지와 함께 결제수단 UI를 직접 만들 때 사용할 수 있습니다.

• background string
  

  아이콘의 배경색입니다.

• text string
  

  아이콘의 텍스트 색입니다.

• cardImgUrl string
  

  카드 실물 이미지 URL입니다. 이 값을 이미지 주소로 사용하면 화면에 카드 실물 이미지를 보여줄 수 있습니다.

• cardProductCode string
  

  PLCC 상품을 구분하는 코드입니다. 카드사에서 발급합니다.

• promotions array
  

  카드사 프로모션 정보가 담기는 배열입니다. 혜택이 큰 순서대로 정렬되어 내려갑니다.

• type string
  

  프로모션 종류입니다. 아래 네 가지 값 중 하나가 돌아옵니다. 상세 정보는 type 이름과 같은 객체에 들어있습니다.

  • CARD_DISCOUNT: 카드 즉시 할인입니다. cardDiscount 객체에 관련 정보가 돌아옵니다.

  • CARD_INTEREST_FREE: 카드 무이자 할부입니다. cardInterestFree 객체에 관련 정보가 돌아옵니다.

  • CARD_POINT: 카드 포인트 할인입니다. cardPoint 객체에 관련 정보가 돌아옵니다.

  • BANK_DISCOUNT: 계좌 할인입니다. bankDiscount 객체에 관련 정보가 돌아옵니다.

• cardDiscount string
  

  카드사의 즉시 할인 정보입니다.

• issuerCode string
  

  프로모션을 진행하는 카드 발급사 두 자리 코드입니다. 카드사 코드를 참고하세요.

• discountAmount string
  

  할인되는 금액입니다.

• minimumPaymentAmount string
  

  카드사 즉시 할인을 적용할 수 있는 최소 결제 금액입니다.

• maximumPaymentAmount string
  

  카드사 즉시 할인을 적용할 수 있는 최대 결제 금액입니다.

• currency string
  

  통화 정보입니다.

• discountcode string
  

  프로모션 코드입니다. 카드사에서 만든 고유한 값으로 결제할 때 함께 넘겨야 하는 값입니다.

• dueDate string
  

  프로모션을 마치는 시점입니다. yyyy-MM-dd 형식입니다. 종료일의 23:59:59까지 행사가 유효합니다.

• balance string
  

  남은 프로모션 예산입니다. 값이 '0'이면 즉시 할인을 적용할 수 없습니다.

• cardInterestFree string
  

  카드 무이자 할부 정보입니다.

  • issuerCode 프로모션을 진행하는 카드 발급사 두 자리 코드입니다. 카드사 코드를 참고하세요.

  • minimumPaymentAmount 무이자 할부를 적용할 수 있는 최소 결제 금액입니다.

  • currency 통화 정보입니다.

  • dueDate 프로모션을 마치는 시점입니다. yyyy-MM-dd 형식입니다. 종료일의 23:59:59까지 행사가 유효합니다.

  • installmentFreeMonths 카드 무이자 할부를 적용할 수 있는 개월 수 입니다.

• cardPoint string
  

  카드 포인트 정보입니다.

  • issuerCode 프로모션을 진행하는 카드 발급사 두 자리 코드입니다. 카드사 코드를 참고하세요.

  • minimumPaymentAmount 카드 포인트를 적용할 수 있는 최소 결제 금액입니다.

  • currency 통화 정보입니다.

  • dueDate 프로모션을 마치는 시점입니다. yyyy-mm-dd 형태입니다. 종료일의 23:59:59까지 행사가 유효합니다.

• accounts array
  

  등록된 계좌 정보입니다.

• id string
  

  결제수단의 아이디입니다.

• type string
  

  계좌 유형입니다. 일반 출금 계좌를 등록하면 WITHDRAW 값이 돌아옵니다.

• accountName string
  

  계좌 이름입니다.

• alias 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: 아이콘의 텍스트 색입니다.
• promotions array
  
• bankDiscount string
  

  계좌 할인 정보입니다.

  • bankCode 프로모션을 진행하는 은행 두 자리 코드입니다. 은행 코드를 참고하세요.

  • discountAmount 할인 금액입니다.

  • minimumPaymentAmount 계좌 할인을 적용할 수 있는 최소 결제 금액입니다.

  • maximumPaymentAmount 계좌 할인을 적용할 수 있는 최대 결제 금액입니다.

  • currency 통화 정보입니다.

  • discountCode 계좌 할인 프로모션 코드입니다. 은행에서 만든 고유한 값으로 결제할 때 함께 넘겨야 하는 값입니다.

  • dueDate 프로모션을 마치는 시점입니다. yyyy-mm-dd 형태입니다. 종료일의 23:59:59까지 행사가 유효합니다.

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

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

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

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

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

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

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

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

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

• paymentKey string
  

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

• orderId string
  

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

• amount number
  

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

• methodId string
  

  결제수단의 ID입니다.

• code string
  

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

• message string
  

  에러 메시지입니다.

• orderId string
  

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