부트페이 결제위젯
결제위젯으로 모든 결제수단을 하나의 UI에 통합하세요.
위젯을 사용하면 PG사의 결제창 대신 선택된 카드사의 결제창이 바로 표시됩니다. 이를 통해 가맹점은 결제 경험을 브랜딩에 맞춰 사용자에게 제공할 수 있습니다.
1
위젯 렌더링하기
Client
주문서 페이지 진입 시 결제 위젯을 렌더링합니다. BootpayWidget.render()를 호출하여 위젯이 표시될 DOM 선택자와 설정 객체를 전달합니다.
주문서 페이지 진입 시점에 미리 주문을 생성하고 재고를 확보해두는 것을 권장합니다. 결제 완료 후 재고 부족으로 인한 취소를 방지할 수 있습니다.
필수 설정
application_id부트페이 관리자에서 발급받은 웹 애플리케이션 IDprice결제 금액sandbox위젯 라이브/테스트 환경 여부 (개발 시true)
hooks 설정
위젯 상태 변화를 감지하여 UI를 동기화합니다.
ready위젯 렌더링 완료 시 호출allTermsAccepted모든 필수 약관 동의 시 호출 (결제 버튼 활성화에 활용)paymentMethodUpdated결제수단 변경 시 호출
2
금액 업데이트하기
Client
선택적립금 사용, 쿠폰 적용 등으로 결제 금액이 변경되면 widget.update()를 호출하여 위젯에 반영합니다.
두 번째 인자를
false로 전달하면 데이터만 업데이트하고 화면을 다시 렌더링하지 않습니다.3
결제 요청하기
Client
Server
부트페이 위젯은 결제 요청 전에 가맹점 서버를 먼저 호출해야 합니다. 가맹점 서버에서 주문을 생성하고, 해당 주문에 대한 결제 승인을 받을 준비를 합니다.
결제 흐름: 주문 생성(order_id 발급) → 결제 승인 요청 → redirect_url 페이지 이동 -> 결제 조회
3-1. 주문 생성 (가맹점 서버)
결제 버튼 클릭 시, 가맹점 내부 서버로 API를 호출합니다. 서버에서 주문을 생성하고 DB에 저장한 후, 주문 정보를 클라이언트에 반환합니다.
order_name주문명payment_method위젯에서 선택된 결제수단 (widget.currentPaymentParameters())coupon_id, mileage_amount(선택) 적용한 쿠폰 ID, 사용 적립금 등 할인 정보
클라이언트에서 전달받은 금액은 위변조 가능성이 있으므로, 서버에서 직접 최종 결제 금액을 계산하고 DB에 저장해두세요. 결제 완료 후 검증 단계에서 이 금액과 비교합니다.
3-2. 결제 요청 (클라이언트)
서버에서 받은 주문 정보로 BootpayWidget.requestPayment()를 호출하여 결제창을 표시합니다.
결제가 완료되면 redirect_url로 지정한 결제결과 페이지로 이동합니다.
order_id서버에서 생성한 주문 IDorder_name주문명price서버에서 계산한 최종 결제 금액pg, method위젯에서 선택된 결제수단 정보redirect_url결제 완료 후 이동할 결제결과 페이지 URL
결제 완료 후
redirect_url로 이동하며, URL 파라미터로 receipt_id, order_id 등이 전달됩니다.결제 완료 또는 실패 시에도
redirect_url로 이동합니다. event 파라미터로 결과를 구분하세요.4
결제 결과 조회 및 검증
Client
Server
redirect_url로 이동한 결제결과 페이지에서 URL 파라미터로 전달된 receipt_id를 사용하여 결제를 조회하고 검증합니다.
URL 파라미터 예시:
/payment/result?receipt_id=abc123&order_id=ORD-123&event=done&status=14-1. URL 파라미터에서 결제 정보 추출 (클라이언트)
결제결과 페이지에서 URL 파라미터로 전달된 정보를 추출합니다.
receipt_id부트페이가 생성한 결제 고유 IDorder_id3-1에서 생성한 주문 IDevent결제 결과 (done: 성공,error: 실패,cancel: 취소)
4-2. 서버에서 결제 조회 API 호출
클라이언트에서 서버 API를 호출하여 결제를 조회합니다. 서버에서는 부트페이 액세스 토큰 발급 후 receipt_id로 결제 조회 API를 호출합니다.
status === 1결제 완료 상태 확인price부트페이에서 실제 결제된 금액
4-3. 금액 대조 및 처리 (서버)
order_id로 가맹점 DB에서 주문 금액을 조회하고, 부트페이 결제 금액과 일치하는지 확인합니다.
금액 일치: 주문 완료 처리 후 결과 화면을 사용자에게 표시합니다.
금액 불일치: 위변조가 의심되므로
bootpay.cancel()로 결제를 즉시 취소하세요.고급 기능
렌더링 옵션
BootpayWidget.render() 호출 시 전달할 수 있는 옵션입니다.
| sandbox | 테스트 모드 여부 (true / false) |
| widget_key | 관리자에서 생성한 위젯 키 (선택) |
| user_token | 브랜드페이 사용자 토큰 (브랜드페이 사용 시), 고유값으로 사용자 식별 |
| use_only_brandpay | 브랜드페이 전용 모드 (true 시 브랜드페이만 표시) |
| use_terms | 약관 표시 여부 (true / false) |
| external_terms | 외부 약관 추가 (배열 형태) |
예시
BootpayWidget.render('#payment-widget', {
application_id: '5b8f6a4d396fa665fdc2b5e7',
price: 39000,
sandbox: true,
widget_key: 'my-widget-key', // 관리자에서 생성한 위젯 키
user_token: 'user-token-string', // 브랜드페이 사용 시
use_only_brandpay: false,
use_terms: true,
external_terms: [
{
pk: 'external-term-1',
title: '개인정보 제3자 제공 동의',
required: 'required', // 'required' 또는 'optional'
url: 'https://example.com/terms'
}
]
})
extra 옵션 (스타일/할부)
렌더링 시 extra 객체로 전달하는 옵션입니다.
| card_quota | 할부 개월 수 배열 (예: [0, 2, 3, 4, 5, 6]) |
| inline_styles | 위젯 커스텀 스타일 (mobile/pc별 containerStyle 설정) |
| deposit_expiration | 가상계좌 입금 만료일 (예: '2024-12-31 23:59:59') |
예시
BootpayWidget.render('#payment-widget', {
application_id: '5b8f6a4d396fa665fdc2b5e7',
price: 39000,
sandbox: true,
extra: {
card_quota: [0, 2, 3, 4, 5, 6], // 일시불, 2~6개월 할부
deposit_expiration: '2024-12-31 23:59:59',
inline_styles: {
mobile: {
containerStyle: {
'padding-top': '24px',
'padding-bottom': '24px',
'padding-left': '16px',
'padding-right': '16px'
}
},
pc: {
containerStyle: {
'padding-top': '36px',
'padding-bottom': '36px',
'padding-left': '36px',
'padding-right': '36px'
}
}
}
}
})
hooks (이벤트 콜백)
위젯 상태 변화를 감지하는 콜백 함수입니다.
| ready | 위젯 렌더링 완료 시 호출 |
| allTermsAccepted | 모든 필수 약관 동의 시 호출 |
| paymentMethodUpdated | 결제수단 변경 시 호출 (선택된 결제수단 정보 전달) |
| termsConsentUpdated | 약관 동의 상태 변경 시 호출 |
| resize | 위젯 크기 변경 시 호출 |
| brandpayWalletUpdated | 브랜드페이 지갑 변경 시 호출 |
예시
BootpayWidget.render('#payment-widget', {
application_id: '5b8f6a4d396fa665fdc2b5e7',
price: 39000,
sandbox: true,
hooks: {
ready: () => {
console.log('위젯 렌더링 완료')
},
allTermsAccepted: () => {
// 모든 약관 동의 시 결제 버튼 활성화
document.getElementById('pay-btn').disabled = false
},
paymentMethodUpdated: (data) => {
// data: { pg, method, ... }
console.log('선택된 결제수단:', data)
},
termsConsentUpdated: () => {
console.log('약관 동의 상태 변경')
},
resize: () => {
console.log('위젯 크기 변경')
},
brandpayWalletUpdated: (wallets) => {
console.log('브랜드페이 지갑:', wallets)
}
}
})
유틸리티 API
위젯 제어를 위한 메서드입니다.
| update(options) | 위젯 옵션 업데이트 (금액 변경 등) |
| rerender() | 위젯 재렌더링 |
| destroy() | 위젯 제거 (페이지 이동 전 권장) |
| isRendered() | 렌더링 여부 확인 (true / false) |
| currentPaymentParameters() | 현재 선택된 결제수단 정보 반환 (pg, method 등) |
| selectPayment(options) | 특정 결제수단 선택 (payment_type, method_alias) |
| isWidgetTypeSubscription() | 구독(정기결제) 위젯 여부 확인 |
예시
// 금액 업데이트 (적립금 사용 시)
widget.update({ price: 36000, tax_free: 0 })
// 위젯 재렌더링
widget.rerender()
// 렌더링 여부 확인
if (widget.isRendered()) {
console.log('위젯이 렌더링되어 있습니다')
}
// 현재 선택된 결제수단 정보 가져오기
const paymentParams = widget.currentPaymentParameters()
// { pg: 'nicepay', method: 'card', ... }
// 특정 결제수단 선택
widget.selectPayment({
payment_type: 'card',
method_alias: '신용카드'
})
// 페이지 이동 전 위젯 제거
widget.destroy()
DOM 이벤트
document.addEventListener()로 수신할 수 있는 이벤트입니다.
| bootpay-widget-ready | 위젯 준비 완료 |
| bootpay-widget-resize | 위젯 크기 변경 |
| bootpay-widget-change-payment | 결제수단 변경 (e.detail로 정보 확인) |
| bootpay-widget-change-terms | 약관 동의 상태 변경 |
| bootpay-all-agree-terms | 모든 약관 동의 |
| bootpayclose | 결제창 닫힘 |
예시
// 위젯 준비 완료 이벤트
document.addEventListener('bootpay-widget-ready', (e) => {
console.log('위젯 준비 완료')
})
// 결제수단 변경 이벤트
document.addEventListener('bootpay-widget-change-payment', (e) => {
console.log('선택된 결제수단:', e.detail)
// e.detail: { pg, method, completed, ... }
})
// 약관 동의 상태 변경 이벤트
document.addEventListener('bootpay-widget-change-terms', (e) => {
console.log('약관 상태:', e.detail)
})
// 모든 약관 동의 이벤트
document.addEventListener('bootpay-all-agree-terms', (e) => {
document.getElementById('pay-btn').disabled = false
})
// 결제창 닫힘 이벤트
document.addEventListener('bootpayclose', (e) => {
console.log('결제창이 닫혔습니다')
})
