브랜드페이 위젯 연동하기

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

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

준비하기

API 키 확인하기

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

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

// 문서 테스트 키
// 토스페이먼츠에 회원 가입하기 전이라면 아래 키로 자동결제를 연동하세요.
const clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq'
const secretKey = 'test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R'

// 내 테스트 키
// 토스페이먼츠에 회원 가입하고 자동결제를 추가 계약한 뒤 아래 키로 자동결제를 연동하세요.
// 로그인하면 문서의 API 키가 모두 내 테스트 키로 변경됩니다.
const clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq'
const secretKey = 'test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R'

JavaScript

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

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

리다이렉트 URL 등록하기

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

1. 브랜드페이 위젯 그리기

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

응답

<!DOCTYPE html>
<html lang="ko">
  <head>
    <meta charset="utf-8" />
    <!--결제위젯 SDK 추가 -->
    <script src="https://js.tosspayments.com/v1/brandpay"></script>
    <link rel="stylesheet" type="text/css" href="/src/style" />
  </head>
  <body>
    <div id="payment-method"></div>
    <!-- 결제하기 버튼 -->
    <button id="payment-button">결제하기</button>
    </div>
    <script>
      const clientKey = "test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq";
      const customerKey = ""; // 상점에서 고객을 구분하기 위해 발급한 고객의 고유 ID로 변경하세요.
      const button = document.getElementById("payment-button");

      // ------  브랜드페이 초기화 ------
      // 브랜드페이 MID와 연결된 clientKey를 입력하세요.
      // customerKey로 나중에 해당 고객의 결제수단, 가입 상태를 관리할 수 있어요.
      // redirectUrl은 인증에 필요합니다. 개발자센터에 등록된 URL을 입력해주세요.
      const brandpay = BrandPay(clientKey, customerKey, {
        redirectUrl: "https://my-store.com/callback-auth"
      });

      // ------  브랜드페이 위젯 객체 생성 ------
      // 결제 금액을 파라미터로 넣어주세요.
      paymentMethodsWidget = brandpay.createPaymentMethodsWidget({
        amount: 50000
      });

      // ------  브랜드페이 렌더링 ------
      // 위젯을 렌더링할 영역을 지정하는 CSS 선택자와 UI 옵션을 설정하세요.
      paymentMethodsWidget.render("#payment-method");

      // ------ 결제 금액 업데이트 ------
      // 쿠폰 적용이나 할인 프로모션 등의 이유로 결제금액을 변경해야 된다면 updateAmount()를 사용하세요.
      async function updateAmount(e) {
        e.preventDefault();
        paymentMethodsWidget.updateAmount(45000);
      }

      // ------ '결제하기' 버튼 누르면 결제창 띄우기 ------
      // 더 많은 결제 정보 파라미터는 SDK 메서드에서 확인하세요.
      button.addEventListener("click", handleSubmit);

      async function handleSubmit(e) {
        e.preventDefault();
        // ------ 위젯 결제 정보 불러오기 ------
        // 결제 금액, 카드 할부 정보 등 결제 구매자가 설정한 결제 정보입니다.
        const widgetPaymentParams = paymentMethodsWidget.getPaymentParams();

        await brandpay
          .requestPayment({
            orderId: "",
            orderName: "테스트",
            // successUrl: "https://my-store.com/success" // 리다이렉트 URL 방식을 사용할 때만 successUrl을 설정하세요
            // failUrl: "https://my-store.com/fail"       // 리다이렉트 URL 방식을 사용할 때만 failUrl을 설정하세요
            ...widgetPaymentParams
          })
          .then(function (data) {
             // 결제 승인 API 호출
          })
          .catch(function (error) {
            // 결제 요청 실패 처리
          });
      }
    </script>
  </body>
</html>

HTML

위젯 UI의 옵션을 설정하는 선택 파라미터와 파라미터 설정에 따라 달라지는 화면은 브랜드페이 위젯 SDK를 참고하세요.

2. 결제수단 등록하고 결제하기

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

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

3. 결제 요청 결과 확인하기

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

https://my-store.com/success?paymentKey={PAYMENT_KEY}&orderId={ORDER_ID}&amount={AMOUNT}

paymentKey: 결제의 키 값입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다. 결제 승인에 사용됩니다.
orderId:주문 ID입니다. 주문한 결제를 식별하는 역할로, 결제를 요청할 때 가맹점에서 만들어서 requestPayment()에 담아 보낸 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 중복되지 않는 고유한 값을 발급해야 합니다. 결제 상태가 변해도 값이 유지됩니다.
amount: 실제로 결제된 금액입니다.

createPaymentMethodsWidget() 메서드에 담아 보낸 결제 금액과 응답으로 돌아온 amount 값이 같은지 반드시 확인해보세요. 클라이언트에서 결제 금액을 조작해 승인하는 행위를 방지할 수 있습니다.

만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요. 적립금이나 쿠폰이 적용된 금액이 맞는지도 확인해보세요.

결제 요청이 실패했을 때

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

https://my-store.com/fail?code={ERROR_CODE}&message={ERROR_MESSAGE}&orderId={ORDER_ID}

3. 결제 승인하기

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

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

base64('test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R:')
        ─────────────────┬───────────────── ┬
                     secretKey              :
                   발급받은 시크릿 키           콜론

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

echo -n 'test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R:' | base64

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

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/brandpay/payments/confirm \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"paymentKey":"{PAYMENT_KEY}","amount":50000,"orderId":"QndBgcRl0rs_vM-SOnud-"}'

4. 결제 완료 후 응답 확인하기

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

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "paymentKey": "",
  "status": "DONE",
  "lastTransactionKey": "",
  "orderId": "",
  "orderName": "토스 티셔츠 외 2건",
  "requestedAt": "2022-06-07T17:20:48+09:00",
  "approvedAt": "2022-06-07T17:21:21+09:00",
  "useEscrow": false,
  "cultureExpense": false,
  "card": {
    "issuerCode": "61",
    "acquirerCode": "31",
    "number": "43301234****123*",
    "installmentPlanMonths": 0,
    "isInterestFree": false,
    "interestPayer": null,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY",
    "amount": 50000
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "cashReceipt": null,
  "cashReceipts": null,
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "BRANDPAY",
  "easyPay": null,
  "country": "KR",
  "failure": null,
  "isPartialCancelable": true,
  "receipt": {
    "url": "https://api.tosspayments.com/v1/payments//checkout"
  },
  "currency": "KRW",
  "totalAmount": 10000,
  "balanceAmount": 10000,
  "suppliedAmount": 9091,
  "vat": 909,
  "taxFreeAmount": 0,
  "method": "카드"
}

JSON

브랜드페이 위젯 SDK

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

createPaymentMethodsWidget(결제 금액)

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

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

// brandpay 객체 생성
var brandpay = BrandPay(clientKey, customerKey, {
  redirectUrl: 'http://example.com'
})

// paymentMethodsWidget 객체 생성
var paymentMethodsWidget = brandpay.createPaymentMethodsWidget({ amount: 10000 }) 

// render() 메서드로 브랜드페이 위젯 렌더
paymentMethodsWidget.render('#payment-methods-widget')

JavaScript

초기화 파라미터

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

render(selector, options)

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

// 위젯 렌더
paymentMethodsWidget.render('#payment-methods-widget')

JavaScript

파라미터

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입니다.

UI 옵션 설정하기

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

destroy()

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

// 생성된 위젯 제거
paymentMethodsWidget.destroy()

JavaScript

updateAmount(결제 금액)

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

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

paymentMethodsWidget.updateAmount(50000)

JavaScript

파라미터

amount 필수 · number
새 결제 금액입니다. 이 금액이 위젯에 반영됩니다.

getPaymentParams()

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

paymentMethodsWidget.getPaymentParams()

JavaScript

결제 정보

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