@bootpay/bp-commerce-sdk

Bootpay Commerce SDK

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

특징

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

설치

NPM

npm install @bootpay/bp-commerce-sdk

Yarn

yarn add @bootpay/bp-commerce-sdk

CDN

<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: '[e-mail]'
  },
  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
• 이메일: [e-mail]