브랜드페이 위젯 연동하기
브랜드페이 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);