Bootpay Commerce SDK

부트페이 커머스 플랫폼을 위한 JavaScript/TypeScript SDK입니다. 커머스 상품 표시, 청구서 결제 요청, 결제 이벤트 관리 기능을 제공합니다.

특징

- 커머스 상품 렌더링: iframe을 통한 상품 페이지 임베딩
- 청구서 결제: popup, iframe, redirect 방식 지원
- 이벤트 기반 통신: postMessage를 통한 양방향 이벤트 처리
- TypeScript 완전 지원: 타입 정의 포함
- 다양한 결제 방식: 카드, 간편결제 등 모든 부트페이 결제 수단 지원

설치

$3

``bash
npm install @bootpay/bp-commerce-sdk
`

$3

`bash
yarn add @bootpay/bp-commerce-sdk
`

$3

`html

`

빠른 시작

$3

웹사이트에 부트페이 커머스 상품을 iframe으로 표시합니다.

`javascript
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')
}
}
})
`

$3

`javascript
BootpayCommerce.requestCheckout({
client_key: 'YOUR_CLIENT_KEY',
request_id: 'order_12345',
name: '상품 주문서',
memo: '고객 요청사항',
user: {
membership_type: 'member',
user_id: 'user123',
name: '홍길동',
phone: '01012345678',
email: 'user@example.com'
},
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

REST API를 이용해 청구서를 생성 후 생성된 청구서의 URL 정보를 가져와 결제 창을 띄웁니다.
위변조 위험이 적은 방법으로 가장 추천하는 방법입니다.

`javascript
BootpayCommerce.requestCheckoutUrl('https://invoice.bootpay.co.kr/invoice/abc123')
.then(response => {
console.log('Payment completed:', response)
})
.catch(error => {
console.error('Payment failed:', error)
})
`

API 레퍼런스

$3

커머스 상품을 지정된 요소에 렌더링합니다.

Parameters:

| Name | Type | Required | Description |
|------|------|----------|-------------|
| selector | string | Yes | CSS 선택자 (예: '#container') |
| options | RequestExModel | Yes | 렌더링 옵션 |

RequestExModel:

`typescript
{
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 // 렌더링 완료 시 호출
}
}
`

$3

청구서 기반 결제를 요청합니다.

Parameters:

| Name | Type | Required | Description |
|------|------|----------|-------------|
| data | CheckoutRequestModel | Yes | 청구서 요청 데이터 |

Returns: Promise - 결제 결과

CheckoutRequestModel:

`typescript
{
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 // 커스텀 메타데이터
extra?: {
open_type: 'popup' | 'iframe' | 'redirect' // 결제창 표시 방식
separately_confirmed?: boolean // 별도 확인 필요 여부
create_order_immediately?: boolean // 즉시 주문 생성 여부
}
}
`

$3

청구서 URL로 결제를 요청합니다.

Parameters:

| Name | Type | Required | Description |
|------|------|----------|-------------|
| url | string | Yes | 청구서 URL |

Returns: Promise - 결제 결과

$3

SDK 환경 모드를 설정합니다.

Parameters:

| Name | Type | Required | Description |
|------|------|----------|-------------|
| env | 'development' \| 'stage' \| 'production' | Yes | 환경 모드 |

`javascript
// 개발 환경
BootpayCommerce.setEnvironmentMode('development')

// 스테이징 환경
BootpayCommerce.setEnvironmentMode('stage')

// 프로덕션 환경 (기본값)
BootpayCommerce.setEnvironmentMode('production')
`

$3

커머스 iframe으로 커스텀 이벤트를 전송합니다.

Parameters:

| Name | Type | Required | Description |
|------|------|----------|-------------|
| eventName | string | Yes | 이벤트 이름 |
| data | any | Yes | 이벤트 데이터 |

$3

알림 창을 숨깁니다.

Parameters:

| Name | Type | Required | Description |
|------|------|----------|-------------|
| eventName | string | No | 이벤트 이름 (기본: 'confirm') |

이벤트 처리

결제 완료 시 done 이벤트가 발생합니다.

`javascript
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 이벤트 페이로드:

`typescript
{
request_id?: string // 요청 ID
metadata?: Record // 메타데이터
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
// ...
}
}
`

사용 시나리오

$3

`javascript
// 특정 카테고리의 상품만 표시
BootpayCommerce.render('#catalog', {
client_key: 'YOUR_CLIENT_KEY',
categories: ['electronics', 'computers'],
extra: {
window: {
height: '1000px'
}
}
})
`

$3

`javascript
BootpayCommerce.requestCheckout({
client_key: 'YOUR_CLIENT_KEY',
request_id: 'inv_' + Date.now(),
name: '월간 구독료',
price: 9900,
extra: {
open_type: 'iframe', // iframe으로 표시
separately_confirmed: true
}
})
`

$3

`javascript
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로 작성되었으며 완전한 타입 정의를 제공합니다.

`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+

개발 환경 설정

`bash


의존성 설치

npm install

개발 모드 실행

npm run build

프로덕션 빌드

npm run deploy
`

보안 고려사항

1. 클라이언트 키 관리: client_key는 공개되어도 안전하지만, 프론트엔드에서만 사용하세요.
2. 서버 검증: 결제 완료 후 반드시 서버에서 부트페이 API로 결제 정보를 재검증하세요.
3. HTTPS 필수: 프로덕션 환경에서는 반드시 HTTPS를 사용하세요.

문제 해결

$3

1. 올바른 CSS 선택자를 사용했는지 확인
2. client_key가 유효한지 확인
3. 브라우저 콘솔에서 에러 메시지 확인

$3

팝업 차단기가 활성화되어 있을 수 있습니다. 사용자 클릭 이벤트 핸들러 내에서 requestCheckout를 호출하세요.

`javascript
button.addEventListener('click', () => {
// 사용자 클릭 직후 호출하면 팝업 차단 방지
BootpayCommerce.requestCheckout({ ... })
})
``

라이선스

Copyright (c) Bootpay. All rights reserved.

지원

- 문서: https://docs.bootpay.co.kr
- 이메일: developer@bootpay.co.kr