@bootpay/bp-commerce-sdk
v1.0.6
Published
부트페이 커머스 플랫폼을 위한 JavaScript/TypeScript SDK입니다. 커머스 상품 표시, 청구서 결제 요청, 결제 이벤트 관리 기능을 제공합니다.
Readme
Bootpay Commerce SDK
부트페이 커머스 플랫폼을 위한 JavaScript/TypeScript SDK입니다. 커머스 상품 표시, 청구서 결제 요청, 결제 이벤트 관리 기능을 제공합니다.
특징
- 커머스 상품 렌더링: iframe을 통한 상품 페이지 임베딩
- 청구서 결제: popup, iframe, redirect 방식 지원
- 이벤트 기반 통신: postMessage를 통한 양방향 이벤트 처리
- TypeScript 완전 지원: 타입 정의 포함
- 다양한 결제 방식: 카드, 간편결제 등 모든 부트페이 결제 수단 지원
설치
NPM
npm install @bootpay/bp-commerce-sdkYarn
yarn add @bootpay/bp-commerce-sdkCDN
<script src="https://js.bootpay.co.kr/commerce/bp-commerce-sdk-{version}.min.js"></script>빠른 시작
1. 커머스 상품 렌더링
웹사이트에 부트페이 커머스 상품을 iframe으로 표시합니다.
import BootpayCommerce from '@bootpay/bp-commerce-sdk'
// 상품 렌더링
BootpayCommerce.render('#product-container', {
client_key: 'YOUR_CLIENT_KEY',
categories: ['category1', 'category2'],
extra: {
window: {
width: '100%',
height: '800px',
resizable: true
},
frame_style: {
background_color: '#ffffff'
}
},
hooks: {
onReady: () => {
console.log('Commerce widget is ready')
}
}
})2. 청구서 결제 요청 (Popup)
BootpayCommerce.requestCheckout({
client_key: 'YOUR_CLIENT_KEY',
request_id: 'order_12345',
name: '상품 주문서',
memo: '고객 요청사항',
user: {
membership_type: 'member',
user_id: 'user123',
name: '홍길동',
phone: '01012345678',
email: '[email protected]'
},
products: [
{
product_id: 'prod_001',
product_option_id: 'opt_001',
quantity: 2
}
],
price: 50000,
tax_free_price: 0,
delivery_price: 3000,
redirect_url: 'https://yourdomain.com/order/complete',
extra: {
separately_confirmed: false,
create_order_immediately: true
}
}).then(response => {
console.log('Checkout created:', response)
}).catch(error => {
console.error('Error:', error)
})3. URL을 통한 청구서 요청
REST API를 이용해 청구서를 생성 후 생성된 청구서의 URL 정보를 가져와 결제 창을 띄웁니다. 위변조 위험이 적은 방법으로 가장 추천하는 방법입니다.
BootpayCommerce.requestCheckoutUrl('https://invoice.bootpay.co.kr/invoice/abc123')
.then(response => {
console.log('Payment completed:', response)
})
.catch(error => {
console.error('Payment failed:', error)
})API 레퍼런스
BootpayCommerce.render(selector, options)
커머스 상품을 지정된 요소에 렌더링합니다.
Parameters:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| selector | string | Yes | CSS 선택자 (예: '#container') |
| options | RequestExModel | Yes | 렌더링 옵션 |
RequestExModel:
{
client_key: string // 부트페이 클라이언트 키
categories?: string[] // 표시할 카테고리 필터
extra?: {
window?: {
width?: string | number // iframe 너비 (기본: '100%')
height?: string | number // iframe 높이 (기본: '600px')
resizable?: boolean // 크기 조절 가능 여부
fullscreen?: boolean // 전체화면 모드
}
frame_style?: {
background_color?: string // 배경색
}
}
hooks?: {
onReady?: () => void // 렌더링 완료 시 호출
}
}BootpayCommerce.requestCheckout(data)
청구서 기반 결제를 요청합니다.
Parameters:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| data | CheckoutRequestModel | Yes | 청구서 요청 데이터 |
Returns: Promise<any> - 결제 결과
CheckoutRequestModel:
{
client_key: string // 부트페이 클라이언트 키
request_id: string // 주문 고유 ID
name: string // 주문서 이름
memo?: string // 메모
user?: {
membership_type?: 'member' | 'guest' // 회원 유형
user_id?: string // 사용자 ID
name?: string // 이름
phone?: string // 전화번호
email?: string // 이메일
}
products?: Array<{
product_id?: string // 상품 ID
product_option_id?: string // 상품 옵션 ID
quantity?: number // 수량
}>
price?: number // 결제 금액
tax_free_price?: number // 면세 금액
delivery_price?: number // 배송비
redirect_url?: string // 결제 완료 후 리다이렉트 URL
usage_api_url?: string // 사용량 기반 API URL
use_auto_login?: boolean // 자동 로그인 사용
use_notification?: boolean // 알림 사용
expired_at?: string // 만료 일시 (ISO 8601)
metadata?: Record<string, any> // 커스텀 메타데이터
extra?: {
open_type: 'popup' | 'iframe' | 'redirect' // 결제창 표시 방식
separately_confirmed?: boolean // 별도 확인 필요 여부
create_order_immediately?: boolean // 즉시 주문 생성 여부
}
}BootpayCommerce.requestCheckoutUrl(url)
청구서 URL로 결제를 요청합니다.
Parameters:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| url | string | Yes | 청구서 URL |
Returns: Promise<any> - 결제 결과
BootpayCommerce.setEnvironmentMode(env)
SDK 환경 모드를 설정합니다.
Parameters:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| env | 'development' \| 'stage' \| 'production' | Yes | 환경 모드 |
// 개발 환경
BootpayCommerce.setEnvironmentMode('development')
// 스테이징 환경
BootpayCommerce.setEnvironmentMode('stage')
// 프로덕션 환경 (기본값)
BootpayCommerce.setEnvironmentMode('production')BootpayCommerce.sendEvent(eventName, data)
커머스 iframe으로 커스텀 이벤트를 전송합니다.
Parameters:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| eventName | string | Yes | 이벤트 이름 |
| data | any | Yes | 이벤트 데이터 |
BootpayCommerce.hideAlert(eventName?)
알림 창을 숨깁니다.
Parameters:
| Name | Type | Required | Description |
|------|------|----------|-------------|
| eventName | string | No | 이벤트 이름 (기본: 'confirm') |
이벤트 처리
결제 완료 시 done 이벤트가 발생합니다.
window.addEventListener('message', (event) => {
if (event.data.event === 'done') {
const orderData = event.data.payload
console.log('주문 번호:', orderData.order_number)
console.log('결제 금액:', orderData.price)
console.log('주문 상품:', orderData.products)
console.log('영수증 정보:', orderData.receipt_success_data)
console.log('사용자 정보:', orderData.user)
// 주문 완료 처리
// ...
}
})done 이벤트 페이로드:
{
request_id?: string // 요청 ID
metadata?: Record<string, any> // 메타데이터
order_number?: string // 주문 번호
order_name: string // 주문명
price: number // 결제 금액
tax_free_price: number // 면세 금액
purchased_at: string // 결제 일시
status: string // 주문 상태
products: CheckoutProduct[] // 주문 상품 목록
receipt_success_data: {
receipt_id: string // 영수증 ID
order_id: string // 주문 ID
price: number // 결제 금액
method: string // 결제 수단
pg: string // PG사
receipt_url: string // 영수증 URL
card_data?: { // 카드 결제 정보
card_company: string // 카드사
card_no: string // 카드 번호 (마스킹)
card_quota: string // 할부 개월
// ...
}
// ...
}
user: { // 주문자 정보
user_id: string
name: string
email: string
phone: string
// ...
}
}사용 시나리오
시나리오 1: 상품 카탈로그 임베딩
// 특정 카테고리의 상품만 표시
BootpayCommerce.render('#catalog', {
client_key: 'YOUR_CLIENT_KEY',
categories: ['electronics', 'computers'],
extra: {
window: {
height: '1000px'
}
}
})시나리오 2: iframe 방식 청구서 결제
BootpayCommerce.requestCheckout({
client_key: 'YOUR_CLIENT_KEY',
request_id: 'inv_' + Date.now(),
name: '월간 구독료',
price: 9900,
extra: {
open_type: 'iframe', // iframe으로 표시
separately_confirmed: true
}
})시나리오 3: 리다이렉트 방식 결제
BootpayCommerce.requestCheckout({
client_key: 'YOUR_CLIENT_KEY',
request_id: 'order_789',
name: '제품 구매',
price: 150000,
redirect_url: 'https://yourdomain.com/payment/callback',
extra: {
open_type: 'redirect' // 페이지 이동
}
})TypeScript 지원
SDK는 TypeScript로 작성되었으며 완전한 타입 정의를 제공합니다.
import BootpayCommerce, {
CheckoutRequestModel,
RequestExModel,
CheckoutDoneData
} from '@bootpay/bp-commerce-sdk'
// 타입 안전한 코드 작성
const invoiceData: CheckoutRequestModel = {
client_key: 'YOUR_CLIENT_KEY',
request_id: 'order_001',
name: '주문서',
price: 10000,
extra: {
open_type: 'popup'
}
}
BootpayCommerce.requestCheckout(invoiceData)브라우저 지원
- Chrome (최신 2개 버전)
- Firefox (최신 2개 버전)
- Safari (최신 2개 버전)
- Edge (최신 2개 버전)
- iOS Safari 12+
- Android Chrome 80+
개발 환경 설정
# 의존성 설치
npm install
# 개발 모드 실행
npm run build
# 프로덕션 빌드
npm run deploy보안 고려사항
- 클라이언트 키 관리:
client_key는 공개되어도 안전하지만, 프론트엔드에서만 사용하세요. - 서버 검증: 결제 완료 후 반드시 서버에서 부트페이 API로 결제 정보를 재검증하세요.
- HTTPS 필수: 프로덕션 환경에서는 반드시 HTTPS를 사용하세요.
문제 해결
iframe이 표시되지 않는 경우
- 올바른 CSS 선택자를 사용했는지 확인
client_key가 유효한지 확인- 브라우저 콘솔에서 에러 메시지 확인
결제 창이 차단되는 경우
팝업 차단기가 활성화되어 있을 수 있습니다. 사용자 클릭 이벤트 핸들러 내에서 requestCheckout를 호출하세요.
button.addEventListener('click', () => {
// 사용자 클릭 직후 호출하면 팝업 차단 방지
BootpayCommerce.requestCheckout({ ... })
})라이선스
Copyright (c) Bootpay. All rights reserved.
지원
- 문서: https://docs.bootpay.co.kr
- 이메일: [email protected]