결제 연동/브랜드페이/연동하기
목차

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

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

이해하기

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

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

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

* 브랜드페이 SDK 및 API를 사용할 때는 브랜드페이 상점아이디(MID)와 연결된 API 개별 연동 키를 사용하세요.

설정하기

상점관리자

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

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

개발자센터

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

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

결제위젯 연동 키 준비하기

토스페이먼츠와 브랜드페이 계약을 완료했다면, 내 상점의 결제위젯 연동 키로 결제위젯을 연동하세요. 토스페이먼츠 계약 이후에만 브랜드페이를 결제위젯으로 사용할 수 있어요.

상점관리자 > 매출·정산 관리 > 내 상점 이름 >'개발 정보' 에서 결제위젯 연동 키를 확인하세요. 아래 그림과 같이 왼쪽 상단에 상점 이름이 나와야 됩니다.

내 상점의 API 키

연동하기

결제위젯에서 브랜드페이를 사용하려면 결제위젯을 먼저 연동하고 아래와 같이 간단한 클라이언트, 서버 작업을 마치면 돼요.

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

1. 결제위젯 그리기

아래 예제 코드는 주문서 페이지에 결제위젯, 이용약관 UI를 그립니다. 결제하기 버튼을 눌러서 결제창을 띄워보세요. 실제로 결제되지 않으니 안심하세요.

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

<head>
<meta charset="utf-8" />
<!-- 결제위젯 SDK 추가 -->
<script src="https://js.tosspayments.com/v1/payment-widget"></script>
</head>
<body>
<!-- 결제위젯, 이용약관 영역 -->
<div id="payment-method"></div>
<div id="agreement"></div>
<!-- 할인 쿠폰 -->
<div>
<input type="checkbox" id="coupon-box" />
<label for="coupon-box"> 5,000원 쿠폰 적용 </label>
</div>
<!-- 결제하기 버튼 -->
<button id="payment-button">결제하기</button>
<script> const clientKey = 'test_gck_docs_Ovk5rk1EwkEbP0W43n07xlzm' const customerKey = "" // 내 상점에서 고객을 구분하기 위해 발급한 고객의 고유 ID const coupon = document.getElementById('coupon-box') const button = document.getElementById('payment-button') // ------ 결제위젯 초기화 ------ const paymentWidget = PaymentWidget(clientKey, customerKey, { // 브랜드페이 설정 파라미터를 추가하세요. brandpay: { // Access Token 발급에 사용되는 리다이렉트 URL redirectUrl: window.location.origin + '/callback-auth', }, }) // ------ 결제 UI 렌더링 ------ // 결제 UI를 렌더링할 위치를 지정합니다. `#payment-method`와 같은 CSS 선택자와 결제 금액 객체를 추가하세요. // DOM이 생성된 이후에 렌더링 메서드를 호출하세요. // https://docs.tosspayments.com/reference/widget-sdk#renderpaymentmethods선택자-결제-금액-옵션 paymentWidget.renderPaymentMethods( '#payment-method', { value: 50000 }, // 렌더링하고 싶은 결제 UI의 variantKey // 아래 variantKey는 문서용 테스트키와 연동되어 있습니다. 멀티 UI를 직접 만들고 싶다면 계약이 필요해요. // https://docs.tosspayments.com/guides/payment-widget/admin#멀티-결제-ui { variantKey: 'BRANDPAY' } // 브랜드페이와 일반결제가 함께 보이는 결제 UI의 variantKey // { variantKey: "BRANDPAY_ONLY" } // 브랜드페이만 추가된 결제 UI의 variantKey ) // ------ 이용약관 UI 렌더링 ------ // 이용약관 UI를 렌더링할 위치를 지정합니다. `#agreement`와 같은 CSS 선택자를 추가하세요. // https://docs.tosspayments.com/reference/widget-sdk#renderagreement선택자-옵션 paymentWidget.renderAgreement( '#agreement', { variantKey: 'AGREEMENT' } // 기본 이용약관 UI 렌더링 ) // ------ 금액 업데이트 ------ // 새로운 결제 금액을 넣어주세요. // https://docs.tosspayments.com/reference/widget-sdk#updateamount결제-금액 coupon.addEventListener('change', function () { if (coupon.checked) { paymentMethodWidget.updateAmount(amount - 5000) } else { paymentMethodWidget.updateAmount(amount) } }) // ------ '결제하기' 버튼 누르면 결제창 띄우기 ------ // 더 많은 결제 정보 파라미터는 결제위젯 SDK에서 확인하세요. // https://docs.tosspayments.com/reference/widget-sdk#requestpayment결제-정보 button.addEventListener('click', function () { paymentWidget.requestPayment({ orderId: "", orderName: '토스 티셔츠 외 2건', successUrl: window.location.origin + '/success', failUrl: window.location.origin + '/fail', customerEmail: 'customer123@gmail.com', }) }) </script>
</body>

2. 카드・계좌 등록하기

브랜드페이 결제수단 등록 화면

만약에 브랜드페이를 처음 사용하는 구매자라면, 위와 같은 UI에서 결제수단을 등록해야 돼요. 카드・계좌 추가하기 이미지는 상점관리자에서 커스터마이징할 수 있어요.

구매자가 카드・계좌 정보를 등록하고 이용약관에 동의하면, redirectUrl의 쿼리 파라미터로 code, customerKey를 전달해요. 서버에서 redirectUrl을 받으면 Access Token을 발급하는 로직을 구현하세요.

https://{ORIGIN}/auth?code={CODE}&customerKey={CUSTOMER_KEY}
  • code: Access Token 발급에 필요한 Authorization Code(임시 인증 코드)입니다.
  • customerKey: 상점에서 만든 고객의 고유 ID입니다.

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

3. Access Token 발급하기

redirectUrl의 쿼리 파라미터 정보로 브랜드페이 Access Token 발급 API를 호출하세요.

먼저 API 인증을 위해 아래와 같이 인증 헤더 값을 만듭니다. 결제위젯 연동 키 > 시크릿 키 뒤에 :을 추가하고 base64로 인코딩합니다. :을 빠트리지 않도록 주의하세요.

토스페이먼츠에서는 기본적으로 Basic 인증 방식을 사용하기 때문이에요. Basic 인증은 인증 정보로 사용자 ID, 비밀번호를 사용해요. 다음과 같이 base64로 인코딩한 “사용자ID:비밀번호” 문자열을 Basic과 함께 인증 헤더에 입력하는 방식이죠.

Authorization: Basic base64({USERNAME}:{PASSWORD})

토스페이먼츠는 시크릿 키를 사용자 ID, 즉 {USERNAME}으로 사용하고, 비밀번호는 따로 넣지 않는 방식이에요. 그래서 마지막에 :만 남게 됩니다. 더 자세한 내용은 토스페이먼츠 콘텐츠 Basic 인증과 Bearer 인증의 모든 것에서 확인해보세요.

base64('test_gsk_docs_OaPz8L5KdmQXkzRz3y47BMw6:')
─────────────────┬─────────────────── ┬
secretKey :
결제위젯 연동 키 > 시크릿 키 콜론

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

echo -n 'test_gsk_docs_OaPz8L5KdmQXkzRz3y47BMw6:' | base64

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

  • 헤더에 Authorization을 추가하고 Basic {인코딩된 시크릿 키 값}을 넣어주세요. 아래 예제 코드를 참고하세요.
  • 요청 본문으로는 앞 단계에서 리다이렉트 URL로 받은 code, customerKey를 넣어주세요. Access Token 최초 발급에는 grantTypeAuthorizationCode로 설정하세요.
요청
curl --request POST \
--url https://api.tosspayments.com/v1/brandpay/authorizations/access-token \
--header 'Authorization: Basic dGVzdF9za19EbnlScFFXR3JObVFFZW5OZG8yVkt3djFNOUVOOg==' \
--header 'Content-Type: application/json' \
--data '{"grantType":"AuthorizationCode","customerKey":"Q0tKjJLcDAMcEtJY0RUYd","code":"RnYX2w532omp6gDQgVNeyqAp"}'

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

Access Token이 잘 발급되고 결제 요청이 성공하면 requestPayment()의 파라미터로 설정했던 successUrl로 이동합니다. successUrl 뒤에 네 가지 쿼리 파라미터가 들어있습니다. 첫 번째 파라미터는 paymentType입니다. 브랜드페이 결제이기 때문에 BRANDPAY로 돌아옵니다.

https://{ORIGIN}/success?paymentType={PAYMENT_TYPE}&paymentKey={PAYMENT_KEY}&orderId={ORDER_ID}&amount={AMOUNT}
  • paymentType: 결제 유형입니다. 브랜드페이 결제는 항상 BRANDPAY입니다.
  • paymentKey: 결제의 키 값입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다. 결제 승인에 사용됩니다.
  • orderId:주문 ID입니다. 주문한 결제를 식별하는 역할로, 결제를 요청할 때 가맹점에서 만들어서 requestPayment()에 담아 보낸 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 중복되지 않는 고유한 값을 발급해야 합니다. 결제 상태가 변해도 값이 유지됩니다.
  • amount: 실제로 결제된 금액입니다.

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

더 자세한 내용은 결제 흐름 이해하기 가이드를 참고하세요.

5. 브랜드페이 결제 승인하기

paymentTypeBRANDPAY라면 브랜드페이 결제 승인 API을 호출하세요. 3. Access Token 발급하기에서 인코딩한 결제위젯 시크릿 키 값을 사용하세요.

  • 헤더에 Authorization을 추가하고 Basic {인코딩된 시크릿 키 값}을 넣어주세요. 아래 예제 코드를 참고하세요.
  • 요청 본문으로는 앞 단계에서 리다이렉트 URL로 받은 paymentKey, orderId, amount를 넣어주세요. 아래 예제 코드에는 내 테스트 결제의 paymentKey 값을 넣어 실행해주세요.
요청
curl --request POST \
--url https://api.tosspayments.com/v1/brandpay/payments/confirm \
--header 'Authorization: Basic dGVzdF9nc2tfZG9jc19PYVB6OEw1S2RtUVhrelJ6M3k0N0JNdzY6' \
--header 'Content-Type: application/json' \
--data '{"paymentKey":"{PAYMENT_KEY}","amount":50000,"customerKey":"Q0tKjJLcDAMcEtJY0RUYd","orderId":"BeFu1pgYMPvk3Kt4kgzqx"}'

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

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

응답
JSON
{
"mId": "tosspayments",
"version": "2022-11-16",
"paymentKey": "",
"status": "DONE",
"lastTransactionKey": "",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"requestedAt": "2022-06-08T15:40:09+09:00",
"approvedAt": "2022-06-08T15:40:49+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"issuerCode": "61",
"acquirerCode": "31",
"number": "12345678****789*",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"amount": 15000
},
"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://dashboard.tosspayments.com/sales-slip?transactionId=KAgfjGxIqVVXDxOiSW1wUnRWBS1dszn3DKcuhpm7mQlKP0iOdgPCKmwEdYglIHX&ref=PX"
},
"checkout": {
"url": "https://api.tosspayments.com/v1/payments//checkout"
},
"currency": "KRW",
"totalAmount": 15000,
"balanceAmount": 15000,
"suppliedAmount": 13636,
"vat": 1364,
"taxFreeAmount": 0,
"method": "카드"
}

자주 묻는 질문

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

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

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

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

더 알아보기

결제위젯 연동하기결제위젯 JavaScript SDK 연동 가이드입니다
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    실시간 문의|이메일 보내기