브랜드페이 연동하기

브랜드페이는 자체 간편결제를 구축하는 서비스입니다.

브랜드페이를 통해서 구매자가 결제수단을 등록하면, 결제수단 정보는 토스페이먼츠 서버에 저장됩니다. 그래서 내 상점에서 다시 구매자의 정보를 불러오려면 OAuth 인증이 필요해요. 대략적인 과정은 아래 흐름도에서 확인해주세요. 브랜드페이를 통해서 구매자가 결제수단을 등록하면, 결제수단 정보는 토스페이먼츠 서버에 저장됩니다. 그래서 내 상점에서 다시 구매자의 정보를 불러오려면 OAuth 인증이 필요해요. 대략적인 과정은 아래 흐름도에서 확인해주세요.

개발자센터의 브랜드페이 메뉴에서 결제수단과 리다이렉트 URL을 설정하세요. 리다이렉트 URL은 브랜드페이 구매자를 인증하는 과정에 필요합니다.

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

토스페이먼츠와 전자결제 계약 전이어도 회원가입하면 나만의 테스트 상점 키를 확인하고 테스트 결제내역, 웹훅 등 기능을 사용할 수 있어요. 로그인한 상태라면 코드의 키 값이 테스트 상점 키입니다.

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

먼저 주문서 페이지에 브랜드페이 결제창을 연동할게요. 아래 코드는 주문서 페이지의 예시에요.

스크립트 태그 또는 패키지 매니저로 토스페이먼츠 SDK를 설치하고, 클라이언트 키로 SDK를 초기화하세요. 다음, brandpay() 메서드로 브랜드페이 인스턴스를 생성하세요. 아래 코드에서는 brandpay라는 인스턴스를 생성했어요.

그럼 이제 결제창을 띄울 준비가 됐어요. 브랜드페이 인스턴스로 brandpay.requestPayment() 메서드를 호출하면 결제 요청이 시작되고, 결제창이 열려요. 메서드의 파라미터로 주문번호, 결제금액, successUrl, failUrl 등 필요한 정보를 설정하세요. 그리고 주문서의 '결제하기' 버튼에 결제 요청 메서드를 이벤트로 등록해주세요.

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

구매자가 카드・계좌 정보를 등록하면, redirectUrl로 이동하고 쿼리 파라미터로 code, customerKey가 추가돼요.

redirectUrl로 받은 쿼리 파라미터 정보를 서버로 전달하세요. 그럼 서버에서는 브랜드페이 Access Token 발급 API를 호출한 준비가 됐어요.

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

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

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

결제창에서 구매자의 결제수단을 인증하는데요. 인증 결과는 성공・실패 리다이렉트 URL로 확인할 수 있어요. 결제 인증이 성공했다면 성공 리다이렉트 URL(successUrl)의 쿼리 파라미터로 결제 정보를 확인하고 검증해주세요. 인증이 실패했다면 이동한 실패 리다이렉트 URL(failUrl)의 쿼리 파라미터로 에러를 확인해주세요.

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

만약에 결제 정보가 틀려서 결제 인증이 실패했다면, failUrl로 이동해요. 해당 URL에는 아래 세 가지 쿼리 파라미터가 추가돼요. 에러 코드와 메시지를 확인해서 구매자에게 적절한 안내 메시지를 보여주세요.

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

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

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

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

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

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