브랜드페이 위젯 연동하기

✅ 브랜드페이 JavaScript SDK로 브랜드페이 위젯을 생성하고 관리할 수 있어요.

✅ 빠르게 시작할 수 있는 위젯 샘플 프로젝트를 기반으로 작성된 가이드입니다.

브랜드페이 위젯은 API 개별 연동 키로 연동하세요.

토스페이먼츠에 회원가입하기 전이라면, 다음 문서 테스트 키로 결제위젯을 연동할 수 있어요.

토스페이먼츠에 회원가입했다면, 로그인 후 내 테스트 키로 결제위젯을 연동하고 개발자센터에서 테스트 결제내역을 확인하세요.

토스페이먼츠와 계약을 완료했다면 상점 테스트 키로 브랜드페이를 연동하세요. 상점 테스트 키는 '상점관리자 > 매출 · 정산 관리 > 내 상점 이름 > 개발 정보'에서 확인하세요.

계약 문의는 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 해주세요.

토스페이먼츠에 회원가입했다면, 개발자센터의 브랜드페이 메뉴에서 리다이렉트 URL을 등록하세요. 리다이렉트 URL은 브랜드페이 사용자를 인증하는 과정에 필요합니다.

아래 예제 코드는 주문서 페이지에 브랜드페이 위젯을 그립니다. 아래와 같이 HTML에 브랜드페이 SDK를 추가하거나 @tosspayments/brandpay-sdk npm 패키지를 사용해주세요. 실제로 결제되지 않으니 안심하세요.

만약에 브랜드페이를 처음 사용하는 구매자라면, '결제하기' 버튼을 눌렀을 때 본인인증을 하고 결제수단을 등록할 수 있어요. 성공적으로 결제수단이 등록되면 바로 결제창이 나와요.

이미 브랜드페이를 사용한 구매자라면, 아래와 같이 등록된 결제수단이 보이고 '결제하기'를 누르면 바로 결제창이 나와요.

결제 요청 결과를 확인할 차례에요. 결제 요청이 성공하면 requestPayment()의 파라미터로 설정했던 (successUrl)의 쿼리 파라미터 또는 Promise를 통해 결제 데이터를 받습니다.

• paymentKey: 결제의 키값입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다. 결제 승인에 사용됩니다.
• orderId: 주문번호입니다. 결제 요청에서 내 상점이 직접 생성한 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 6자 이상 64자 이하의 문자열입니다. 각 주문을 식별하는 역할로, 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 orderId는 유지됩니다.
• amount: 결제할 금액입니다.

결제 요청이 실패하면 설정했던 결제 실패 페이지(failUrl)로 이동하거나 에러 객체를 Promise로 받습니다. 에러 목록을 확인하세요.

브랜드페이 결제 승인 API를 호출해서 마지막 단계를 완료합니다. 먼저 API 인증을 위해 아래와 같이 인증 헤더 값을 만듭니다.

시크릿 키 뒤에 :을 추가하고 base64로 인코딩합니다. :을 빠트리지 않도록 주의하세요.

아래 명령어를 터미널에서 실행하면 인코딩된 값을 얻을 수 있습니다.

인코딩된 값을 Basic 인증 헤더에 넣고 요청 본문도 추가하세요. 앞 단계에서 리다이렉트 URL로 받은 paymentKey, orderId, amount를 넣어주세요. 아래 예제 코드에는 내 테스트 결제의 paymentKey 값을 넣어 실행해주세요.

결제 승인에 성공하면 HTTP 200 OK와 Payment 객체를 받습니다.

브랜드페이 위젯은 브랜드페이 SDK에서 제공하는 기능으로 결제수단을 등록하고 선택하는 UI, 결제수단마다 달라지는 프로모션 정보를 보여주는 UI를 제공합니다.

브랜드페이 위젯을 생성합니다. createPaymentMethodsWidget()으로 생성된 객체는 브랜드페이 위젯을 관리할 수 있는 네 가지 메서드를 제공합니다.

• render(): 브랜드페이 위젯 렌더
• destroy(): 브랜드페이 위젯 제거
• updateAmount(): 브랜드페이 위젯의 금액 정보 업데이트
• getPaymentParams(): 브랜드페이 위젯에서 선택한 결제 정보 제공

• amount 필수 · number
  

  결제할 금액입니다. 이 금액에 따라 선택한 결제수단에서 적용할 수 있는 할부 개월 수, 카드 프로모션 정보가 다르게 표시됩니다.

브랜드페이 위젯이 설정한 영역에 렌더됩니다. 렌더 영역은 selector 파라미터로 추가하세요.

• selector 필수 · string
  

  브랜드페이 위젯을 렌더링할 위치를 지정합니다. <div>와 같은 HTML 요소를 선택할 수 있는 CSS 선택자를 사용합니다.

  예를 들어 <div id="payment-methods-widget">에 브랜드페이 위젯을 렌더링하려면, #payment-methods-widget을 전달해야 합니다.

• options string
  

  브랜드페이 위젯에 보여줄 결제수단과 UI 설정입니다.

• methodType string
  

  위젯에 보여줄 결제수단을 선택합니다. 카드, 계좌 중 하나입니다. 예를 들어 카드를 선택하면 등록한 결제수단 중 카드만 노출됩니다.

• methodId
  

  위젯에서 기본 결제수단으로 선택할 결제수단의 ID입니다.

• ui object
  

  위젯 UI를 변경할 수 있는 옵션입니다. 각 UI 옵션에 따라 달라지는 위젯 화면은 이미지를 참고하세요.

• ui.promotionSection.summary.visible boolean
  

  혜택 배지 영역을 보여주거나 숨깁니다. 혜택 배지 영역에서는 즉시 할인 대상 카드 정보 등을 간략히 보여줍니다. 기본값은 true입니다.

• ui.promotionSection.description.visible boolean
  

  결제 혜택 영역을 보여주거나 숨깁니다. 기본값은 true입니다.

• ui.promotionSection.description.defaultOpen boolean
  

  결제 혜택의 상세 설명을 보여주거나 숨깁니다. 각 카드사의 결제 혜택을 자세히 설명합니다. 기본값은 false입니다.

options.ui 파라미터 값에 따라 달라지는 위젯을 아래 이미지로 확인해보세요.

렌더된 브랜드페이 위젯을 제거합니다.

초기화할 때 설정한 결제 금액을 변경합니다. 쿠폰 적용 등으로 결제 금액이 바뀌었을 때 사용합니다.

메서드를 실행하면 위젯에 새로운 금액 정보가 반영됩니다.

• amount 필수 · number
  

  새 결제 금액입니다. 이 금액이 위젯에 반영됩니다.

브랜드페이 위젯의 결제 정보가 돌아옵니다.

• amount number
  

  결제 금액입니다.

• cardInstallmentPlan number
  

  신용 카드의 할부 개월 수입니다. 값을 넣으면 해당 할부 개월 수로 결제가 진행됩니다. 값을 넣지 않으면 고객이 할부 개월 수를 선택할 수 있습니다.

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

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

• methodId string
  

  현재 위젯에서 선택되어 있는 결제수단의 ID입니다.

• useCardPoint nullable · boolean
  

  카드사 포인트 사용 여부입니다.

• cashReceipt nullable · object
  

  현금영수증 정보입니다. 계좌로 결제할 때만 값이 있습니다.

• type string
  

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

• registrationNumberType string
  

  현금영수증 번호 타입입니다. MOBILE(휴대폰 번호), BUSINESS_REGISTRATION(사업자등록번호), CASH_RECEIPT_CARD(현금영수증 카드 번호) 중 하나입니다.

• registrationNumber number
  

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