JS SDK/브랜드페이
목차

Version 2

링크 복사브랜드페이 JavaScript SDK

브랜드페이 결제수단 위젯을 렌더링하고 결제를 요청하는 메서드를 알아봅니다.

링크 복사브랜드페이

링크 복사tossPayments.brandpay()

브랜드페이를 초기화합니다. 브랜드페이는 내 상점의 자체 간편결제를 쉽게 만들 수 있는 결제 서비스예요.

링크 복사파라미터

  • params 필수 · object

    브랜드페이 초기화 정보입니다.

    • customerKey 필수 · string

      구매자를 식별하는 고유 아이디입니다.

      이메일・전화번호나 자동 증가하는 숫자와 같이 유추가 가능한 값은 안전하지 않아요. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 중 최소 1개를 포함하는 최소 2자 이상 최대 50자 이하의 문자열이어야 합니다.

    • redirectUrl string

      브랜드페이 결제 과정에서 Access Token 발급을 위해 필요한 URL입니다. Access Token은 브랜드페이 고객을 식별하고 고객의 결제 권한을 증명합니다. 값을 넣지 않으면 개발자센터의 브랜드페이 메뉴에 최초로 등록한 리다이렉트 URL이 기본값으로 들어갑니다.

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

링크 복사응답

아래 메서드를 호출할 수 있는 브랜드페이 객체를 반환합니다.

  • requestPayment function

    브랜드페이 결제창을 띄웁니다. 자세히 >

  • changePassword function

    브랜드페이 결제 비밀번호를 변경하는 창을 띄웁니다. 자세히 >

  • addPaymentMethod function

    브랜드페이에 새로운 결제수단을 추가합니다. 자세히 >

  • openSettings function

    브랜드페이 결제 관리 설정창을 띄웁니다. 자세히 >

  • changeOneTouchPay function

    원터치결제 설정을 변경합니다. 자세히 >

  • isOneTouchPayEnabled function

    원터치결제 활성화 여부를 확인합니다. 자세히 >

링크 복사brandpay.requestPayment()

브랜드페이 결제창을 띄웁니다. 구매자의 최초 결제라면 결제수단을 등록하고, 결제가 요청돼요. 이미 결제수단을 등록한 구매자라면 결제수단을 선택하고 결제 비밀번호를 입력하면 바로 결제가 돼요.

결제 요청은 Redirect 방식과 Promise 방식을 지원하고 있어요. 결제 요청이 끝나고 결과를 확인하는 방법의 차이인데요. Redirect 방식을 선택하면 파라미터로 설정한 successUrl 또는 failUrl로 결제 요청의 결과를 확인할 수 있어요. Promise 방식을 선택하면 Promise로 돌아오는 객체로 결과를 확인할 수 있어요. 브랜드페이 결제에서는 모바일, PC 환경에서 Redirect 방식, Promise 방식 둘 다 지원해요.

링크 복사파라미터

  • paymentRequest 필수 · object

    결제 요청 정보입니다.

    • amount 필수 · object

      결제 금액 정보입니다.

      • currency 필수 · "KRW"

        결제 통화입니다. 브랜드페이는 KRW 결제만 지원합니다.

      • value 필수 · number

        결제 금액입니다.

    • orderId 필수 · string

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

    • orderName 필수 · string

      구매상품입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.

    • customerEmail string

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

    • customerName string

      구매자명입니다. 최대 길이는 100자입니다.

    • taxFreeAmount number

      결제 금액 중 면세 금액입니다. 면세 상점 혹은 복합 과세 상점으로 계약된 상점만 사용하세요. 자세한 내용은 세금 처리 가이드에서 확인하세요.

    • methodId string

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

    • metadata object

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

    • card object

      구매자가 카드를 선택하면 결제에 적용되는 옵션입니다.

      • cardInstallmentPlan number

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

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

      • useCardPoint boolean

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

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

        * 추가 계약이 필요한 파라미터입니다. 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

      • discountCode string

        카드 즉시 할인 코드입니다. methodId 파라미터가 있을 경우 적용됩니다.

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

    • transfer object

      구매자가 계좌를 선택하면 결제에 적용되는 옵션입니다.

      • cashReceipt enum

        현금영수증 발급 정보를 담는 객체입니다.

      • isCulturalExpenses boolean

        문화비(도서, 공연 티켓, 박물관·미술관 입장권 등) 지출 여부입니다.

      • discountCode string

        계좌 즉시 할인 코드입니다. methodId 파라미터가 있을 경우 적용됩니다.

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

    • successUrl string

      결제 요청이 성공하면 리다이렉트되는 URL입니다. https://www.example.com/success와 같이 오리진을 포함한 형태로 설정해주세요.

      리다이렉트되면 URL의 쿼리 파라미터로 amount, orderId, paymentKey가 추가돼요.

    • failUrl string

      결제 요청이 실패하면 리다이렉트되는 URL입니다. https://www.example.com/fail와 같이 오리진을 포함한 형태로 설정해주세요.

      리다이렉트되면 URL의 쿼리 파라미터로 에러 코드와 메시지를 확인할 수 있어요.

링크 복사응답

결제 요청이 성공하면 파라미터로 설정한 successUrl로 이동해요. 쿼리 파라미터의 amount 값이 메서드 파라미터로 설정한 amount와 같은지 반드시 확인하고 브랜드페이 결제 승인 API를 호출해서 결제를 완료하세요.

결제 요청이 실패하면 파라미터로 설정한 failUrl로 이동해요. 쿼리 파라미터로 에러 코드와 메시지를 확인하세요.

Redirect 방식에서는 URL이 이동하기 때문에 void가 응답됩니다.

    링크 복사brandpay.addPaymentMethod()

    브랜드페이에 새로운 결제수단을 추가합니다. 카드 또는 계좌를 추가할 수 있어요.

    링크 복사응답

      링크 복사brandpay.openSettings()

      브랜드페이 결제 관리 설정창을 띄웁니다. 결제수단 관리, 비밀번호 설정, 원터치결제 설정, 탈퇴 등 다양한 설정을 구매자가 직접 변경할 수 있어요.

      링크 복사응답

        링크 복사brandpay.changePassword()

        브랜드페이 결제 비밀번호를 변경하는 창을 띄웁니다. 기존 비밀번호를 입력하고 새로운 비밀번호를 등록할 수 있어요.

        링크 복사응답

          링크 복사brandpay.changeOneTouchPay()

          원터치결제 설정을 변경합니다. 원터치결제는 브랜드페이의 자체 FDS로 안전하다고 판단되는 결제는 비밀번호 입력 없이 편리하게 결제를 완료할 수 있는 기능입니다.

          링크 복사응답

            링크 복사brandpay.isOneTouchPayEnabled()

            원터치결제 활성화 여부를 확인합니다.

            링크 복사응답

            • isEnabled boolean

              원터치결제 활성화 여부입니다. 원터치결제가 설정되어 있다면 true, 설정되어 있지 않으면 false입니다.