브랜드페이 JavaScript SDK에서 브랜드페이 위젯을 생성하고 관리할 수 있는 메서드를 제공합니다. 빠르게 시작할 수 있는 위젯 샘플 프로젝트로 브랜드페이 위젯을 사용하는 방법을 알아봅니다.
이 가이드는 이미 브랜드페이를 연동한 가맹점을 대상으로 브랜드페이 위젯을 추가하는 방법을 안내합니다.
가입 및 계정 설정, 기본 연동 과정은 브랜드페이 연동하기를 참고해서 진행하세요.
Github에 공개된 브랜드페이 샘플 프로젝트의 가이드를 따라 샘플 프로젝트 실행을 준비하세요. 샘플 프로젝트가 성공적으로 준비되었다면 브라우저에서 http://localhost:3000
에 접속했을 때 아래와 같은 화면을 확인할 수 있습니다.
샘플 프로젝트에서 주로 사용할 파일은 다음과 같습니다.
public
ㄴ brandpay.js
views
ㄴ /fail.html
ㄴ /index.html
ㄴ /success.html
index.js
/public/brandpay.js
,/views/index.html
에는 SDK를 통해 브랜드페이 위젯을 렌더링하고 결제할 수 있는 코드가 있습니다./views/success.html
,/views/fail.html
는 결제 성공 및 실패 결과에 따라 리다이렉트 될 페이지입니다.index.js
는 사용자 인증 및 결제 요청 로직을 처리하는 코드가 포함되어있는 서버 코드입니다.
그럼 지금부터 어떤 과정을 거쳐 전체 샘플 프로젝트가 완성됐는지 알아봅니다.
먼저 결제 화면을 보여줄 /views/index.html
에 브랜드페이 SDK script와 SDK 관련 로직을 처리하는 /static/brandpay.js
를 추가합니다.
<html lang="ko">
<head>
<meta charset="utf-8" />
<title>브랜드페이 위젯 샘플 프로젝트</title>
<!-- BrandPay SDK script 추가 -->
<script type="text/javascript" src="https://js.tosspayments.com/v1/brandpay"></script>
<!-- BrandPay SDK 로직 추가 -->
<script type="text/javascript" defer src="/static/brandpay.js"></script>
</head>
</html>
/public/brandpay.js
에서는 API 키 설정 및 브랜드페이 객체, 결제위젯 객체 초기화를 준비합니다.
// API 키 설정
// 문서: https://docs.tosspayments.com/guides/brandpay/integration#api-키-설정-및-sdk-준비
const clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq';
const customerKey = 'CUSTOMER_KEY'; // 상점에서 고객을 구분하기 위해 발급한 고객의 고유 ID로 변경하세요.
// brandpay 초기화
const brandpay = BrandPay(clientKey, customerKey, {
redirectUrl: window.location.origin + '/callback-auth',
});
// 결제위젯 객체
let paymentMethodsWidget = null;
결제할 금액을 파라미터로 추가해 createPaymentMethodsWidget()
를 호출하면 paymentMethodsWidget
객체가 초기화 됩니다.
let paymentMethodsWidget = null;
initialize();
async function initialize() {
// paymentMethodsWidget 객체 초기화
paymentMethodsWidget = brandpay.createPaymentMethodsWidget({ amount: 1000 });
}
초기화 된 paymentMethodsWidget
은 브랜드페이 위젯을 관리할 수 있는 메서드를 제공합니다. 브랜드페이 위젯을 렌더링하는 메서드는 render()
입니다. render()
의 파라미터로 위젯을 렌더링할 영역을 지정하는 CSS 선택자와 UI 옵션을 설정하세요.
위젯을 렌더링할 영역은 /view/index.html
에서 payment-methods-widget
으로 정의되어 있습니다. 즉 render()
의 첫 번째 파라미터는 payment-methods-widget
입니다.
<body>
<form id="payment-form">
<!-- 위젯을 렌더할 영역 -->
<div id="payment-methods-widget"></div>
<button id="submit">결제하기</button>
</form>
</body>
이제 UI 옵션까지 추가해서 render()
를 호출합니다.
let paymentMethodsWidget = null;
initialize();
async function initialize() {
// 브랜드페이 위젯 객체 초기화
paymentMethodsWidget = brandpay.createPaymentMethodsWidget({ amount: 50000 });
// 브랜드페이 위젯 렌더
paymentMethodsWidget.render('#payment-methods-widget', {
// UI 옵션
ui: {
promotionSection: {
summary: {
visible: true,
},
description: {
visible: true,
defaultOpen: true,
},
},
},
});
}
위젯에서 직접 결제수단을 등록해보세요. 아래와 같이 등록되었다면 이제 결제할 수 있습니다.
위젯이 잘 렌더되었다면 이제 결제수단을 선택하고 결제를 진행해봅니다. 위젯에서 설정한 결제 정보를 requestPayment()
에 넘겨야 합니다. 결제 정보는 getPaymentParams()
를 실행해서 얻을 수 있습니다.
initialize();
// ...
document
.querySelector('#payment-form')
.addEventListener('submit', handleSubmit);
// 결제 하기
async function handleSubmit(e) {
e.preventDefault();
// 위젯 결제 정보
const widgetPaymentParams = paymentMethodsWidget.getPaymentParams();
await brandpay.requestPayment({
orderId: 'ORDER_ID', // 주문에 대한 고유한 ID 값
orderName: '생수 외 1건', // 결제에 대한 주문명
successUrl: window.location.origin + '/success',
failUrl: window.location.origin + '/fail',
...widgetPaymentParams,
});
}
결제 요청에 성공하면 successUrl
로 이동합니다. 만약 successUrl
없이 요청했다면 requestPayment()
가 반환하는 Promise가 resolve 됩니다. 자세한 내용은 브랜드페이 SDK 페이지에서 확인해보세요.
상점 서버에서는 돌아온 값의 유효성을 확인한 뒤 결제 승인 API를 호출합니다.
//...
// 최종 결제 승인
app.post('/confirm-payment', async (req, res) => {
try {
await axios.post(
`https://api.tosspayments.com/v1/brandpay/payments/confirm`,
{
customerKey: req.body.customerKey,
paymentKey: req.body.paymentKey,
orderId: req.body.orderId,
amount: req.body.amount,
},
{
headers: {
// [TODO] Basic 인증 방식의 사용자명과 비밀번호는 콜론으로 구분해서 `사용자명:비밀번호`로 추가합니다. 상점의 시크릿 키를 사용자명으로, 비밀번호는 공백으로 추가한 뒤 base64로 인코딩하세요.
// 문서: https://docs-staging.tosspayments.com/guides/brandpay/auth#2-access-token-발급
Authorization: `Basic ${Buffer.from(SECRET_KEY + ":", "utf8").toString(
"base64"
)}`,
"Content-Type": "application/json",
},
}
)
res.status(200).send('OK');
} catch (error) {
console.error(error.response.data.message)
res.status(500).send(error.response.data.message)
};
})
결제가 성공적으로 승인되었다면 HTTP 상태 코드 200
이 돌아오고, 결제 성공 페이지로 이동합니다.
만약 처음에 설정한 결제 금액에서 쿠폰 적용이나 할인 프로모션이 적용된 새로운 금액으로 바꿔야 한다면 updateAmount()
를 사용하세요.
paymentMethodsWidget.updateAmount(45000);