전제조건
•
결제위젯의 Basic 요금제(무료)가 아닌 Pro 요금제(유료)를 이용해야 합니다. (현재는 Pro 버전을 공식적으로 공개하기 전이다보니 필요시 문의를 주시면 설정해드리고 있습니다.)
•
결제위젯에 브랜드페이를 이용하기 위해서는 브랜드페이를 이용할 수 있는 상점아이디(MID)가 발급된 상태여야 합니다. 브랜드페이 계약을 위해서는 고객센터로 문의 바랍니다.
설명
용어
•
결제위젯: 주문서 내 결제수단을 위젯으로 노출합니다. 카드, 계좌이체, 간편결제(네이버페이, 카카오페이..), 가상계좌 등의 일반 결제 수단을 노출합니다.
•
브랜드페이 위젯: 가맹점의 자체 간편결제의 결제수단 선택창을 노출합니다.
•
결제위젯에 브랜드페이 추가: 주문서 내 일반 결제수단과 가맹점 자체 간편결제 수단 선택창을 한번에 노출합니다.
각 케이스별 화면을 보시면 더 쉽게 이해하실 수 있습니다.
상황별 화면
결제위젯만 이용했을 때 화면
브랜드페이 위젯만 이용했을 때 화면
결제위젯과 브랜드페이를 함께 이용했을 때 화면
결제위젯에 브랜드페이를 추가했을 때 연동 범위
브랜드페이만 연동한다면 BrandPay 객체를 이용해서 연동하면 됩니다. 하지만 결제위젯에 브랜드페이를 함께 연동한다면 PaymentWidget 객체만 이용해도 브랜드페이를 연동하실 수 있습니다. 다만 PaymentWidget 객체는 주문서 내 결제창만 그려주기 때문에 만약 결제창 화면 외 브랜드페이의 추가 기능(예: 서비스의 마이페이지에서 설정 페이지 열기, 계좌만 추가하는 페이지 바로 열기 등)을 이용하고 싶으시다면 BrandPay 객체를 추가로 이용하셔야 합니다. BrandPay 객체를 추가로 이용하는 경우 브랜드페이 MID와 연결된 clientKey를 이용하는 것을 잊지 말아주세요.
사용 기능 | 사용해야 하는 객체 | 필요한 Key 값 |
브랜드페이만 사용 | Brandpay 객체 | 브랜드페이 MID의 clientKey |
결제위젯에서 브랜드페이 기본 기능 사용 | PaymentWidget 객체 | 결제위젯 MID의 clientKey |
PaymentWidget 객체,
Brandpay 객체 | 결제위젯 MID의 clientKey,
브랜드페이 MID의 clientKey |
조금 더 개발적인 레벨에서 디테일하게 설명드리자면 결제위젯에 브랜드페이를 함께 사용하면 PaymentWidget 객체는 BrandPay 객체를 내장하여 BrandPay 객체의 renderPaymentMethods, requestPayment, updateAmount 함수들을 대신 호출해준다고 이해해주시면 됩니다.
결제위젯에 브랜드페이를 추가했을 때 필요한 개발 작업
Front-end 코드의 수정은 거의 없으며 브랜드페이의 기본 기능만 이용하고 싶으신 경우 서버 코드는 Access Token 발급, 결제 승인 API 정도만 구현하셔도 됩니다. 추가 기능을 이용하고 싶으신 경우 브랜드페이 API 문서에 있는 다른 API를 이용하셔도 됩니다.
상점관리자 설정
1.
[상점관리자] > [결제위젯] > [결제 UI 설정]에서 브랜드페이를 켤 환경을 선택합니다.
2.
[브랜드페이] 메뉴를 클릭한 후 [사용 설정]의 스위치를 켭니다.
3.
결제위젯과 연결할 브랜드페이의 상점아이디(MID)를 선택하고 [연결하기] 버튼을 클릭하여 연결을 완료합니다.
연동
Back-end
필수로 구현되어야 하는 endpoint와 그 구현 내용은 다음과 같습니다.
구현해야하는 endpoint | 설명 |
requestPayment 메서드에서 설정한 successUrl | 결제위젯에 브랜드페이를 함께 이용하는 경우 successUrl로 amount, orderId, paymentKey 외에 paymentType이라는 parameter가 추가되어 돌아옵니다.
쿼리 파라미터로 넘어온 paymentMethod의 값이
- PAYMENT 인 경우 결제위젯 secret key를 이용하여 코어 API의 결제 승인 API를 호출합니다.
- BRANDPAY인 경우 브랜드페이 secret key를 이용하여 브랜드페이 승인 API를 호출합니다. |
브랜드페이 SDK에서 설정한 redirectUrl | |
Front-end
PaymentWidget 객체만 이용하시면 됩니다.
const paymentWidget = PaymentWidget(clientKey, customerKey, {
brandpay: {
redirectUrl: `/brandpay/callback-auth`
}
});
const paymentMethodsWidget = paymentWidget.renderPaymentMethods('#payment-method', 20_000);
paymentWidget.requestPayment({
orderId: 'AD8aZDpbzXs4EQa-UkIX6',
orderName: '리팩터링 2판 외 1권',
successUrl: '/payment/success',
failUrl: '/fail',
customerEmail: 'customer123@gmail.com', // 고객 이메일 (선택)
customerName: '김토스', // 고객 이름 (선택)
})
TypeScript
복사
•
만약 결제위젯으로 제공하는 브랜드페이 기능 외 브랜드페이 SDK에서 제공하는 전체 API를 이용하고 싶으시다면 BrandPay 객체와 브랜드페이 client key를 이용하여 구현해주세요.