목차

브랜드페이 연동하기

✅ 브랜드페이로 내 상점만의 자체 간편결제 시스템을 구축할 수 있어요.

✅ 일반결제, 브랜드페이를 한 번에 연동할 수 있어요.

이해하기

이 가이드는 결제위젯으로 브랜드페이를 연동하는 방법을 알려드려요. 브랜드페이를 별도로 연동하는 것 보다 훨씬 간편하게 연동할 수 있어요.

결제위젯으로 브랜드페이를 연동하면 다음과 같이 결제수단 영역에 브랜드페이와 일반 결제수단을 둘 다 보여줄 수 있어요.

결제위젯에 브랜드페이 추가하기

결제위젯, 브랜드페이는 각자 다른 상점아이디(MID)를 가지고 있어요. 각 MID에는 클라이언트 키, 시크릿 키가 발급돼요.

  • 결제위젯 SDK, 코어 API에는 결제위젯 클라이언트 키, 시크릿 키를 사용하세요.

  • 브랜드페이 SDK, 브랜드페이 API에는 브랜드페이 클라이언트 키, 시크릿 키를 사용하세요.

결제위젯에 브랜드페이를 추가하면 브랜드페이의 기능을 모두 이용할 수 있어요. 만약에 브랜드페이의 추가 기능(브랜드페이 설정 열기, 계좌만 추가하기 등)을 사용하거나 UI/UX를 커스터마이징하고 싶다면 브랜드페이 SDK 또는 브랜드페이 API를 함께 사용해주세요.

설정하기

상점관리자

상점관리자의 결제 UI 설정 메뉴로 들어가세요. 등록된 결제 UI에 이용서비스 > 브랜드페이가 있는지 확인하세요. 만약 없다면 이용 서비스 > 추가하기 +를 눌러서 기존 결제 UI에 브랜드페이 서비스를 추가하세요.

상점관리자에서 결제위젯에 브랜드페이 추가하기

개발자센터

개발자센터의 브랜드페이 페이지에서 리다이렉트 URL을 추가하세요. 리다이렉트 URL로 고객 인증에 필요한 정보를 받을 수 있어요.

브랜드페이 리다이렉트 URL 등록

연동하기

결제위젯에서 브랜드페이를 사용하려면 먼저 결제위젯을 연동한 뒤 브랜드페이 사용을 위한 연동을 이어서 진행해야 합니다. 결제위젯 연동 후 간단한 클라이언트, 서버 작업만으로 결제위젯에 브랜드페이를 추가할 수 있습니다.

결제위젯에 브랜드페이를 추가하면 다음과 같은 결제 흐름이 가능해요.

토스페이먼츠 결제위젯에 브랜드페이 추가하기

먼저 결제위젯을 연동하세요. 연동을 마쳤다면 위젯 설정 파라미터에 리다이렉트 URL을 추가하고, 브랜드페이 결제 승인을 연동합니다.

클라이언트: 리다이렉트 URL 추가하기

결제위젯 객체를 초기화할 때 아래와 같이 options 파라미터로 브랜드페이 리다이렉트 URL을 추가하세요.

<head>

  <meta charset="utf-8" />

  <title>결제하기</title>

  <script src="https://js.tosspayments.com/v1/payment-widget"></script>

</head>

<body>

  <script>
    const clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq' // 결제위젯 클라이언트 키
    const customerKey = ''
    const paymentWidget = PaymentWidget(clientKey, customerKey, { 
      // 결제위젯에 브랜드페이 추가하기
      brandpay: {
        // Access Token 발급에 사용되는 리다이렉트 URL
        redirectUrl: 'http://my-store.com/brandpay/callback-auth'
      }
    })
  </script>

</body>

초기화 파라미터

  • clientKey 필수 · string

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

  • customerKey 필수 · string

    고객 ID입니다. 다른 사용자가 이 값을 알게 되면 악의적인 사용을 할 수 있어 자동 증가하는 숫자는 안전하지 않습니다. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요. 영문 대소문자, 숫자, 특수문자 -, _, =, ., @ 를 최소 1개 이상 포함한 최소 2자 이상 최대 300자 이하의 문자열이어야 합니다.

  • options object

    결제위젯에 추가할 옵션입니다.

  • brandpay object

    결제위젯에 브랜드페이를 추가할 때 설정합니다. redirectUrl이 담긴 객체를 넘기세요.

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

customerKey는 고객을 특정하는 값으로 다른 사용자가 이 값을 탈취하면 악의적인 사용을 할 수 있습니다. customerKey의 보안을 강화하기 위해 Access Token을 발급할 때 세션을 통해 customerKey를 비교하여 동일한 고객인지 확인하는 로직을 추가할 수 있습니다.

클라이언트 작업 마무리하기

결제위젯 객체를 초기화했다면 아래와 같이 결제위젯을 렌더링하고 결제창을 띄워보세요.

paymentWidget.renderPaymentMethods(

  '#payment-method',

   { value: 10000 },

   { variantKey: 'BRANDPAY'} // 브랜드페이가 추가된 결제 UI의 variantKey

)



paymentWidget.requestPayment({

  orderId: 'AD8aZDpbzXs4EQa-UkIX6',

  orderName: '토스 티셔츠 외 2건',

  successUrl: 'http://localhost:8080/success', // 결제 승인에 사용되는 성공 리다이렉트 URL

  failUrl: 'http://localhost:8080/fail',       // 결제 승인에 사용되는 실패 리다이렉트 URL

})
JavaScript

서버: 브랜드페이 결제 연동하기

Access Token을 발급하고 브랜드페이 결제를 승인하는 로직을 추가해주세요.

1. Access Token 발급

브랜드페이를 최초로 사용하는 고객이 브랜드페이 결제를 선택하면, 결제수단을 등록하고 이용 약관에 동의하는 흐름이 이어져요. 더 자세한 내용은 브랜드페이 인증 가이드에서 확인하세요. 이 과정에 성공하면 redirectUrl로 이동합니다.

https://{ORIGIN}/auth?code={CODE}&customerKey={CUSTOMER_KEY}

redirectUrl의 쿼리 파라미터 정보로 Access Token 발급 API를 호출하세요. Basic 인증 헤더에는 브랜드페이 시크릿 키와 콜론을 base64로 인코딩해서 넣습니다.

curl --request POST \

  --url https://api.tosspayments.com/v1/brandpay/authorizations/access-token \

  --header 'Authorization: Basic dGVzdF9za19hQlg3emsyeWQ4eW9Yd29KMGdxVng5UE9McUtROg==' \

  --header 'Content-Type: application/json' \

  --data '{"grantType":"AuthorizationCode","customerKey":"c6thB674j9vCU4XsvcPk","code":"RnYX2w532omp6gDQgVNeyqAp"}'

2. 성공 리다이렉트 URL 확인하기

Access Token이 잘 발급되면 successUrl로 이동합니다.

https://{ORIGIN}/success?paymentKey={PAYMENT_KEY}&orderId={ORDER_ID}&amount={AMOUNT}&paymentType={PAYMENT_TYPE}

요청한 결제 금액과 successUrl로 돌아온 amount 값이 같은지 반드시 확인해보세요. 만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요. 클라이언트에서 결제 금액을 조작하는 행위를 방지할 수 있습니다.

더 자세한 내용은 토스페이먼츠 공식 블로그 포스트를 참고하세요.

3. 브랜드페이 결제 승인 API 호출하기

브랜드페이 결제 승인 API 요청 본문에는 성공 리다이렉트 URL로 받은 paymentKey, orderId, amount와 customerKey를 넣습니다. 헤더에는 브랜드페이 시크릿 키와 콜론을 base64로 인코딩해서 넣습니다.

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

base64('test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R:')

        ─────────────────┬───────────────── ┬

                     secretKey              :

                   발급받은 시크릿 키           콜론

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

echo -n 'test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R:' | base64

인코딩된 값을 Basic 인증 헤더에 넣고 요청 본문을 추가하세요.

요청
curl --request POST \

  --url https://api.tosspayments.com/v1/brandpay/payments/confirm \

  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \

  --header 'Content-Type: application/json' \

  --data '{"paymentKey":"5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6","amount":"10000","customerKey":"c6thB674j9vCU4XsvcPk","orderId":"a4CWyWY5m89PNh7xJwhk1"}'

자주 묻는 질문

아니요. 결제위젯 SDK로 생성한 객체로 브랜드페이의 모든 기능을 사용할 수 있습니다. 하지만 만약에 커스텀 UI/UX를 만들고 싶다면 브랜드페이 SDK 및 API를 사용하세요.

아니요. 브랜드페이 결제수단 위젯은 브랜드페이 결제만 가능한 위젯입니다. 결제위젯에 브랜드페이를 추가하면 브랜드페이 결제, 일반결제(카드, 계좌이체, 가상계좌 등)를 한 번에 볼 수 있어요.

아니요. 결제위젯 SDK로 기본 브랜드페이 기능을 모두 사용할 수 있지만 추가 커스터마이징이 필요하다면 브랜드페이 SDK도 자유롭게 사용하면 됩니다.

결제창을 띄울 때 요청한 결제 금액과 성공 리다이렉트 URL로 받은 결제 금액이 같은지 반드시 확인하세요. 클라이언트에서 결제 금액을 조작하는 것을 방지하고, 최종적으로 적립금이나 쿠폰이 잘 적용됐는지 확인할 수 있어요.

네. customerKey는 회원을 식별하는 고유한 키 값입니다. 같은 회원인 경우 결제위젯 생성자에서 입력한 값과 브랜드페이 생성자에서 입력한 값이 동일해야 합니다.

더 알아보기

결제위젯 연동하기결제위젯 JavaScript SDK 연동 가이드입니다
  • 더 궁금한 내용이 있나요?
    자주 묻는 질문
  • 코드 샘플을 참고하세요
    TossPayments GitHub
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기