브랜드페이 연동하기

브랜드페이에서는 자체 간편결제에 사용할 수 있는 UI를 쉽게 가져다 쓸 수 있도록 JavaScript SDK를 제공합니다.

빠르게 시작할 수 있는 샘플 프로젝트를 통해 자체 간편결제를 구축하는 과정을 알아봅니다.

흐름도

준비하기

가입 및 계정 설정

토스페이먼츠 홈페이지에 가입하세요. 사업자 번호가 아직 없더라도 개발을 시작할 수 있습니다. 가입한 계정의 ID를 기술지원팀에 알려주면 브랜드페이 테스트 연동을 위한 계정 설정이 진행됩니다.

설정이 완료되면 아래와 같이 브랜드페이에서 제공할 결제 수단과 개발 과정에서 사용할 리다이렉트 URL을 추가할 수 있습니다. 만약 개발 정보 페이지에서 브랜드페이 설정이 보이지 않는다면 기술지원팀에 계정 설정이 올바르게 진행되었는지 문의해주세요.

이미지

테스트 연동을 마친 뒤 라이브 연동을 진행하려면 브랜드페이 소개 페이지의 도입 문의하기를 통해 요청해주세요

API 키 준비

개발 정보 페이지의 기본 설정에서 테스트용 API 키를 확인해주세요.

클라이언트 키는 브라우저에서 결제창을 연동할 때 사용되는 키입니다. 시크릿 키는 API 요청을 위해 사용합니다. 각각 프론트엔드, 서버 개발에 사용합니다. 시크릿 키는 브라우저에 노출되면 안 됩니다.

API 키에 대한 더 자세한 내용은 API 사용하기 페이지를 참고하세요.

리다이렉트 URL 추가

브랜드페이로 결제하려면 사용자 인증 과정이 반드시 필요합니다.

인증을 위해 Access Token 발급에 사용할 리다이렉트 URL인 http://localhost:3000/callback-auth를 개발 정보 페이지에 등록해주세요.

샘플 프로젝트 준비

Github에 공개된 브랜드페이 샘플 프로젝트의 가이드를 따라 샘플 프로젝트 실행을 준비하세요.

샘플 프로젝트가 성공적으로 준비되었다면 브라우저에서 http://localhost:3000/checkout 페이지로 접속했을 때 아래와 같은 화면을 확인할 수 있습니다.

페이지 예시 이미지

샘플 프로젝트에서 주요하게 사용할 파일 구조는 다음과 같습니다.

views
ㄴ /checkout.html
ㄴ /fail.html
ㄴ /success.html
index.js

views/checkout.html에는 SDK를 통해 결제창을 열 수 있는 주요 코드가 포함됩니다. 결제 성공 및 실패 결과에 따라 리다이렉트 될 페이지가 각각 success.html, fail.html로 생성되어 있습니다.

최상위의 index.js는 사용자 인증 및 결제 요청 로직 처리를 위한 코드가 포함되어있는 서버 코드입니다.

사용자 인증하기

API 키 설정 및 SDK 준비

서버와 클라이언트 코드에 있는 시크릿 키와 클라이언트 키를 내 상점의 키 값으로 변경합니다.

index.js
// [TODO] 아래 키는 테스트용 시크릿 키입니다. 계정 설정이 진행된 후에는 내 상점의 키 값으로 변경하세요.
// [NOTE] 시크릿 키는 외부에 노출되어서는 안됩니다.
const SECRET_KEY = 'test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R'
JavaScript
views/checkout.html
<script> var clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq' </script>
HTML

키 설정을 했다면 결제 화면을 보여줄 views/checkout.html에 브랜드페이 SDK script를 추가하고 SDK에서 제공하는 BrandPay 객체를 초기화합니다.

views/checkout.html
<!-- BrandPay SDK script 추가 -->
<script src="https://js.tosspayments.com/v1/brandpay"></script>
<script> // [TODO] 아래 키는 테스트용 클라이언트 키입니다. 계정 설정이 진행된 후에는 내 상점의 키 값으로 변경하세요. var clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq' // [TODO] 상점에서 고객을 구분하기 위해 발급한 고객의 고유 ID로 변경하세요. var customerKey = 'CUSTOMER_KEY' // ... // BrandPay 객체 초기화 var brandpay = BrandPay(clientKey, customerKey, { // [TODO] 상점 개발 정보 페이지에 추가한 리다이렉트 URL이 있다면 아래 값을 변경하세요. redirectUrl: 'http://localhost:3000/callback-auth', }) </script>
HTML

초기화를 위해 필수로 설정해야 하는 파라미터는 결제가 이루어질 상점을 특정하는 클라이언트 키, 결제할 고객을 특정하는 고객 ID, 결제할 고객 인증에 사용할 리다이렉트 URL 세 가지 입니다.

초기화 파라미터

  • clientKey 필수 · string

    클라이언트 키는 브라우저에서 결제창을 연동할 때 사용되는 키입니다. 토스페이먼츠에서 상점에 발급합니다. 개발 정보 페이지에서 발급된 키 값을 확인할 수 있습니다.

  • customerKey 필수 · string

    상점에서 고객을 구분하기 위해 발급한 고유 ID입니다. 영문 대소문자, 숫자, 특수문자 -_=.@ 로 최소 1자 이상 최대 50자 이하여야 합니다.

  • redirectUrl 필수 · string

    리다이렉트 URL은 고객이 브랜드페이를 사용해서 결제할 수 있다는 권한을 증명하는 과정에서 필요한 필수 파라미터입니다. 고객이 브랜드페이 사용 약관에 동의하면 Access Token을 발급하기 위해 필요한 정보를 브랜드페이 서버에서 리다이렉트 URL과 함께 넘겨주기 때문입니다. 개발 설정 페이지에 이 값이 추가되어 있어야 합니다.

결제창 띄우기

SDK 초기화가 완료되면 BrandPay 객체에서 제공하는 결제창을 띄우는 메서드 requestPayment를 실행할 수 있습니다.

아래와 같이 views/checkout.html에 버튼을 추가하고, 결제창을 띄울 수 있는 메서드를 연결합니다.

views/checkout.html
<script> function requestPayment() { brandpay.requestPayment({ amount: 5000, // 결제 금액 orderId: orderId, // 주문에 대한 고유한 ID 값 orderName: '토스 티셔츠 외 2건', // 결제에 대한 주문명 }) } </script>
<button onclick="requestPayment()">결제하기</button>
HTML

requestPayment 실행을 위해 필수로 추가해야 하는 파라미터는 결제 금액, 상점에서 주문을 구분하기 위해 만든 주문 ID와 주문명 세 가지 입니다.

필수 파라미터

  • amount 필수 · number

    결제되는 금액입니다.

  • orderId 필수 · string

    상점에서 주문 건을 구분하기 위해 발급한 고유 ID입니다. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.

  • orderName 필수 · string

    결제에 대한 주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.

* 선택 파라미터에 대한 더 자세한 정보는 JavaScript SDK 문서에서 확인해보세요.

약관 동의 진행하기

메서드가 성공적으로 실행됐다면 아래와 같은 약관 동의 화면이 뜹니다. 동의 후 계속 버튼을 누르면 인증 단계로 넘어갑니다.

약관 동의 화면

Access Token 발급받기

Access Token은 브랜드페이 API를 사용하는 사용자를 식별하는데 필요한 인증 토큰입니다.

약관 동의가 성공적으로 완료되었다면 이전 과정에서 설정한 리다이렉트 URL로 아래와 같이 Access Token 발급에 필요한 값들이 돌아옵니다.

https://localhost:3000/callback-auth?code={AUTHORIZATION_CODE}&customerKey={CUSTOMER_KEY}

Access Token 발급 API를 요청하기 위해 리다이렉트 URL에 포함되어 돌아온 임시 인증 코드인 code와 고객 ID인 customerKey를 파라미터로 포함하세요. 처음으로 Access Token을 발급받는 것이기 때문에 토큰 타입을 나타내는 grantType은 AuthorizationCode로 설정해야 합니다.

index.js
// Access Token 발급 받기
app.get('/callback-auth', async (req, res) => {
await axios.post(
'https://api.tosspayments.com/v1/brandpay/authorizations/access-token',
JSON.stringify({
grantType: 'AuthorizationCode',
// Access Token 발급을 위해 리다이렉트 URL에 포함되어 돌아온 code와 customerKey 전달
code: req.query.code,
customerKey: req.query.customerKey,
}),
{
headers: {
// [TODO] Basic 인증 방식의 사용자명과 비밀번호는 콜론으로 구분해서 `사용자명:비밀번호`로 추가합니다. 상점의 시크릿 키를 사용자명으로, 비밀번호는 공백으로 추가한 뒤 base64로 인코딩하세요.
Authorization: `Basic ${Buffer.from(SECRET_KEY + ':', 'utf8').toString( 'base64' )}`,
'Content-Type': 'application/json',
},
}
)
// 성공(HTTP status 200) 응답
res.sendStatus(200)
})
JavaScript

Access Token은 한 번 발급된 뒤에는 SDK에서 자동으로 관리하기 때문에 추가적인 처리가 필요하지 않습니다. 위 과정이 완료되면 브랜드페이 서버가 SDK를 사용하는 사용자가 인증되고 결제를 진행할 수 있습니다.

더 자세한 인증 과정은 브랜드페이 인증 문서를 참고하세요.

본인 확인하기

고객이 처음으로 브랜드페이를 사용한다면 최초 1회에 한하여 본인 확인을 진행합니다.

본인 확인 이미지

결제하기

결제 수단 및 결제 비밀번호 등록

사용자 인증 과정까지 성공적으로 진행되었다면 결제 수단을 등록할 수 있습니다.

결제 수단 등록 이미지

결제 수단이 성공적으로 등록되면 등록한 결제 수단 중 하나를 선택하고 '결제하기' 버튼을 누르세요. 브랜드페이를 이용한 최초 결제라면 먼저 결제할 때 사용할 비밀번호를 설정한 뒤 결제하게 됩니다.

비밀번호 추가 이미지

결제 요청

성공적으로 결제 요청이 진행되었다면 requestPayment가 반환하는 Promise가 resolve 되고 그 결과로 결제를 특정하는 결제 키(paymentKey)와 주문 ID, 결제 금액이 돌아옵니다.

views/checkout.html
<!-- ... -->
<script> // ... brandpay .requestPayment({ amount: 5000, // 결제 금액 orderId: orderId, // 주문에 대한 고유한 ID 값 orderName: '토스 티셔츠 외 2건', // 결제에 대한 주문명 }) .then(res => { // 결제 승인 요청 return axios.post('http://localhost:3000/confirm-payment', res) }) .then(() => { // 결제 성공 페이지(/views/success.html)로 리다이렉트 window.location.href = 'http://localhost:3000/success' }) .catch(err => { if (err.code == 'USER_CANCEL') { console.log('사용자 취소') } else { console.log('기타 에러 상황', err.code, err.message) // 결제 실패 페이지(/views/fail.html)로 리다이렉트 window.location.href = 'http://localhost:3000/fail' } }) </script>
<!-- ... -->
HTML

상점 서버에서는 돌아온 값에 대한 유효성을 확인한 뒤 결제 승인 API를 호출합니다.

index.js
// [TODO] 아래 키는 테스트용 시크릿 키입니다. 내 상점의 키 값으로 변경하세요.
// [NOTE] 시크릿 키는 외부에 노출되어서는 안됩니다.
const SECRET_KEY = 'test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R'
// ...
// 최종 결제 승인
app.post('/confirm-payment', async (req, res) => {
await axios.post(
`https://api.tosspayments.com/v1/payments/${req.body.paymentKey}`,
{
orderId: req.body.orderId,
amount: req.body.amount,
},
{
headers: {
// [TODO] Basic 인증 방식의 사용자명과 비밀번호는 콜론으로 구분해서 `사용자명:비밀번호`로 추가합니다. 상점의 시크릿 키를 사용자명으로, 비밀번호는 공백으로 추가한 뒤 base64로 인코딩하세요.
Authorization: `Basic ${Buffer.from(SECRET_KEY + ':', 'utf8').toString( 'base64' )}`,
'Content-Type': 'application/json',
},
}
)
res.status(200).send('OK')
})
JavaScript

결제가 성공적으로 승인되었다면 HTTP 상태 코드 200이 돌아오고, 결제 성공 페이지로 이동합니다.

결제 완료 페이지

내용이 도움 되셨나요?
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기