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

Version 2

새로 나온

결제위젯으로 편리하게 브랜드페이를 연동하세요. 브랜드페이는 자체 간편결제 시스템 구축하는 결제 서비스예요.

아래 이미지의 우측 화면과 같은 토스페이먼츠 UI로 빠르고 편리하고 브랜드페이를 연동하고 싶다면 결제위젯을 연동하세요. 결제 UI에서 브랜드페이와 일반 결제수단을 함께 사용하거나 브랜드페이를 단독으로 사용할 수 있어요.

결제위젯 - 브랜드페이

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

기본 브랜드페이 기능을 모두 사용할 수 있지만 추가 커스터마이징이 필요하다면 브랜드페이 메서드와 함께 자유롭게 사용할 수도 있어요.

브랜드페이 결제수단 관리

브랜드페이 결제수단 관리

결제위젯 어드민 설정하기

결제위젯 어드민에 등록된 결제 UI에 이용서비스 > 브랜드페이가 있는지 확인하세요. 만약 없다면 이용 서비스 > 추가하기 +를 눌러서 기존 결제 UI에 브랜드페이 서비스를 추가하세요.

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

리다이렉트 URL 등록하기

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

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

API 키 준비하기

개발자센터의 API 키 메뉴에서 결제위젯 연동 키를 확인하세요.

토스페이먼츠와 전자결제를 완료했다면 개발자센터의 API 키 메뉴에서 브랜드페이로 계약된 상점아이디(MID)를 선택한 다음에 클라이언트 키와 시크릿 키를 확인하세요. 테스트 키와 라이브키의 차이점도 확인하고 연동을 시작하세요.

결제위젯 연동 API 키

아니요. 결제위젯으로 브랜드페이를 연동하려면 토스페이먼츠와 전자결제 계약이 필요합니다. 계약 이후에 발급되는 테스트 결제위젯 연동 키로 테스트가 가능해요.


1. 결제위젯 렌더하기

먼저 주문서 페이지에 결제 UI, 약관 UI를 렌더하고 결제창을 연동할게요. 아래 코드는 주문서 페이지의 예시에요.

클라이언트 쪽에 토스페이먼츠 SDK를 설치하고, 클라이언트 키로 SDK를 초기화하세요. 다음, widgets() 메서드로 결제위젯 인스턴스를 생성하세요. brandpay 파라미터에 개발자센터에 등록한 리다이렉트 URL을 꼭 추가해주세요. 아래 코드에서는 widgets라는 인스턴스를 생성했어요.

주문서 페이지에 결제위젯, 약관 UI 영역을 지정하고, 각 UI를 렌더링하세요. 그럼 이제 결제창을 띄울 준비가 됐어요. widgets.requestPayment() 메서드를 호출하면 결제 요청이 시작되고, 결제창이 열려요. 메서드의 파라미터로 주문번호, successUrl, failUrl 등을 설정하세요. 그리고 주문서의 '결제하기' 버튼에 결제 요청 메서드를 이벤트로 등록해주세요.

위 코드를 실행한 다음에 '결제하기' 버튼을 누르면 아래와 같은 결제창이 열려요. 브랜드페이를 처음 사용하는 구매자라면, 결제수단을 등록해야 돼요. 테스트하고 싶은 결제수단을 선택하고 결제 정보를 입력하세요. 테스트 클라이언트 키를 사용했다면 실제로 결제되지 않으니 안심하세요.

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

2. 리다이렉트 URL로 이동하기

구매자가 카드・계좌 정보를 등록하면, redirectUrlcode, customerKey를 전달해요.

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

Access Token 발급에 필요한 Authorization Code(임시 인증 코드)입니다.

3. Access Token 발급하기

redirectUrl 정보로 브랜드페이 Access Token 발급 API를 호출하세요.

먼저 시크릿 키와 :을 base64로 인코딩해서 Basic 인증 헤더를 아래와 같이 만들어주세요. :을 빠트리지 않도록 주의하세요. 비밀번호가 없다는 것을 알리기 위해 시크릿 키 뒤에 콜론을 추가합니다. 시크릿 키는 클라이언트, GitHub 등 외부에 노출되면 안 됩니다.

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

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

오류원인

API 키를 잘못 입력하면 UNAUTHORIZED_KEY 에러가 발생합니다.

해결 방법

  • 클라이언트 키와 매칭된 시크릿 키를 사용하고 있는지 확인하세요. API 키는 토스페이먼츠에 로그인한 뒤에 개발자센터의 API 키 메뉴에서 확인할 수 있어요.

  • 시크릿 키 인코딩을 다시 확인하세요. 시크릿 키 뒤에 :을 추가하고 base64로 인코딩해서 사용해야 됩니다.

Access Token 발급 API의 인증 헤더에 인코딩한 시크릿 키 값을 추가하세요. 요청 본문으로는 앞 단계에서 리다이렉트 URL로 받은 code, customerKey를 넣어주세요. Access Token 최초 발급에는 grantTypeAuthorizationCode로 설정하세요.

그럼 아래와 같이 accessToken, refreshToken이 응답돼요. 만약에 브랜드페이 API로 구매자의 결제수단을 관리하거나 회원 탈퇴 기능을 사용하고 싶다면 토큰 값을 저장하고 사용하세요. 하지만 해당 기능을 SDK 또는 상점관리자를 통해서 사용하고 싶다면 토큰을 저장하지 않아도 돼요.

4. 성공・실패 리다이렉트 URL로 이동하기

결제 요청이 성공했어요

결제 요청이 성공하면 successUrl로 이동해요. 해당 URL에 아래 세 가지 쿼리 파라미터가 추가돼요.

쿼리 파라미터의 amount 값과 setAmount()value 파라미터 값이 같은지 반드시 확인하세요. 클라이언트에서 결제 금액을 조작하는 행위를 방지할 수 있습니다. 만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요.

서버에 paymentKey, amount, orderId 값을 저장하세요. paymentKey는 토스페이먼츠에서 각 주문에 발급하는 고유 키 값이에요. 결제 승인, 취소, 조회 등에 사용되기 때문에 꼭 저장해주세요.

브랜드페이 결제의 paymentType은 항상 BRANDPAY입니다. 기타 결제는 모두 NORMAL입니다.

결제 요청이 실패했어요

결제 요청이 실패하면 failUrl로 이동해요. 해당 URL에는 아래 두 가지 쿼리 파라미터가 추가돼요. 에러 코드와 메시지를 확인해서 구매자에게 적절한 안내 메시지롤 보여주세요.

오류원인

구매자에 의해 결제가 취소되면 PAY_PROCESS_CANCELED 에러가 발생합니다. 결제 과정이 중단된 것이라서 failUrlorderId가 전달되지 않아요.

오류원인

결제가 실패하면 PAY_PROCESS_ABORTED 에러가 발생합니다.

해결 방법

오류원인

구매자가 입력한 카드 정보에 문제가 있다면 REJECT_CARD_COMPANY 에러가 발생합니다.

해결 방법

  • 오류 메시지를 확인하고 구매자에게 안내를 해주세요.

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

마지막 단계로 브랜드페이 결제 승인 API을 호출하세요.

브랜드페이 결제 승인 API 헤더에 앞서 인코딩한 결제위젯 시크릿 키 값을 추가하세요. 요청 본문 파라미터에는 앞 단계에서 리다이렉트 URL로 받은 paymentKey, orderId, amount를 넣어주세요. 아래 예제 코드에는 내 테스트 결제의 paymentKey 값을 넣어 실행해주세요.

6. 응답 확인하기

결제 승인이 성공했어요

결제 승인 API의 결과로 HTTP 200 OK와 함께 Payment 객체가 돌아오면 결제가 정상적으로 완료됐어요.

Payment 객체에 구매자가 선택한 결제수단 정보가 있는지 확인하세요. 카드로 결제했다면 아래와 같이 card 필드에 카드 정보를 확인할 수 있어요.

응답으로 받은 Payment 객체가 아래 예시와 다르다면 API 버전을 확인하세요. 개발자센터의 API 키 메뉴에서 설정된 API 버전을 확인하고 변경할 수 있어요. API 버전 업데이트 사항은 릴리즈 노트에서 확인할 수 있습니다

결제 승인이 실패했어요

결제 승인에 실패하면 HTTP 4XX 또는 5XX 코드와 에러 객체를 받습니다. 결제 승인의 전체 오류 목록은 에러 코드를 참고하세요. 테스트 환경에서 결제 승인 실패를 재현해보고 싶다면 토스페이먼츠 API 테스트 헤더를 사용해보세요.

오류원인

결제 승인에서 요청에 문제가 있으면 NOT_FOUND_PAYMENT_SESSION 에러가 발생합니다.

해결 방법

  • 결제 요청이 완료된 이후 10분 이내에 결제를 승인해야 됩니다. 10분이 지나면 결제 데이터가 유실되어 승인이 불가합니다.

  • 결제 요청했을 때 돌려받은 paymentKey와 결제 승인에 사용한 paymentKey가 같은 값인지 확인하세요.

  • 결제 요청에 사용한 클라이언트 키와 결제 승인에 사용한 시크릿 키가 매칭된 키값인지 확인하세요.

오류원인

카드사에서 해당 카드를 거절했을 때 REJECT_CARD_COMPANY 에러가 발생합니다. 원인은 비밀번호 오류, 한도 초과, 포인트 부족 등 다양합니다.

해결 방법

에러 메시지를 확인해서 원인을 파악하고 고객에게 올바른 안내를 해주세요.

오류원인

API 키값 또는 주문번호가 최초 요청한 값과 다르면 FORBIDDEN_REQUEST가 발생합니다.

해결 방법

  • 결제 요청에 사용한 클라이언트 키와 API 호출에 사용한 시크릿 키가 매칭된 키값인지 확인하세요.

  • orderId, paymentKey 값이 최초 결제 요청한 값과 같은지 확인하세요.

오류원인

API 키를 잘못 입력하면 UNAUTHORIZED_KEY 에러가 발생합니다.

해결 방법

  • 클라이언트 키와 매칭된 시크릿 키를 사용하고 있는지 확인하세요. API 키는 토스페이먼츠에 로그인한 뒤에 개발자센터의 API 키 메뉴에서 확인할 수 있어요.

  • 시크릿 키 인코딩을 다시 확인하세요. 시크릿 키 뒤에 :을 추가하고 base64로 인코딩해서 사용해야 됩니다.


더 알아보기

결제 취소하기
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    실시간 문의|이메일 보내기