Bootpay 커머스 매뉴얼

시작하기

환경 설정

프로젝트 생성 · 커머스 키 발급 · SDK 설치 · 인증 확인, 네 단계예요.

이 문서는 Bootpay Commerce 연동을 시작하기 위한 기본 환경을 준비하는 방법을 설명해요. 아래 순서대로 진행하면 프로젝트 생성, 커머스 키 발급, SDK 설치, 서버 인증 확인까지 끝낼 수 있어요.

공통 결제 설정도 같은 프로젝트에서 사용해요

커머스 SDK는 주문·상품·고객 흐름을 다루지만 실제 결제는 Bootpay 결제 설정을 함께 사용해요. PG사 활성화, Sandbox, 결제수단 설정은 결제 매뉴얼의 환경 설정도 같이 확인해요.

설정 순서

회원 가입

Bootpay 관리자에서 회원가입 후 사업자 정보를 등록해요.

프로젝트 생성

관리자 대시보드에서 프로젝트를 생성해요. 같은 프로젝트 안에서 결제 설정과 커머스 API 키를 관리해요.

커머스 연동키 생성

관리자 → 개발자 설정 > API 연동키에서 커머스용 client_key와 secret_key를 발급해요.

결제창 호출에 쓰는 Client Key와 서버에서 커머스 용 연동키를 헷갈리지 않는 것이 중요해요. 커머스 키는 서버 비밀값으로 저장하고 프론트엔드에 노출하지 않아요.

PG사와 결제수단 설정

관리자 → 결제 설정에서 사용할 PG사와 결제수단을 활성화해요. 개발 단계에서는 Sandbox 모드로 먼저 테스트해요.

웹훅 URL 등록

주문·구독 상태를 서버에서 보정하려면 웹훅 URL을 등록해요. 자세한 설정은 주문 웹훅 설정에서 확인해요.

SDK 설치

커머스 연동은 보통 클라이언트 SDK와 서버 SDK를 같이 사용해요.

  • 클라이언트 SDK: 체크아웃·결제창 호출, 사용자 이벤트 수신
  • 서버 SDK: 커머스 API 호출, 주문 조회, 고객·상품 관리, 구독 운영, 검증·웹훅 후속 처리

커머스 클라이언트 SDK

체크아웃 주문서(BootpayCommerce.requestCheckout)를 여는 SDK 예요. 아래 결제 클라이언트 SDK 와 다른 패키지​​고, default export 라 중괄호 없이 가져와요.

npm install @bootpay/bp-commerce-sdkbash
import BootpayCommerce from '@bootpay/bp-commerce-sdk'javascript
웹 전용이에요

커머스 주문서는 웹 리디렉트 방식이라 모바일 앱에서는 WebView 로 열어요. 앱에서 결제창만 띄운다면 아래 결제 클라이언트 SDK 를 써요.

결제 클라이언트 SDK

결제창·본인인증 등 결제 기능용이에요. 커머스 연동에서도 결제 설정은 같은 프로젝트를 쓰기 때문에 함께 필요할 수 있어요.

npm install @bootpay/client-jsbash

서버 SDK

npm install @bootpay/backend-jsbash

최신 버전

각 SDK 의 최신 버전이에요. 기준일은 2026-09-08 이고, 확인처 링크에서 항상 최신 값을 볼 수 있어요.

클라이언트 SDK

SDK 패키지 최신 버전 확인처
커머스 JavaScript @bootpay/bp-commerce-sdk 1.0.8 npm
커머스 JavaScript · CDN bp-commerce-sdk-{version}.min.js 1.0.7 npm 보다 늦게 올라와요
JavaScript @bootpay/client-js 5.3.1 npm
JavaScript · CDN bootpay-{version}.min.js 5.3.1 npm 패키지와 같은 버전을 써요
Android · Kotlin io.github.bootpay:android 5.2.1 Maven Central
iOS · Swift Bootpay 5.2.1 CocoaPods
Flutter · Dart bootpay 5.3.1 pub.dev
React Native react-native-bootpay-api 13.15.1 npm

서버 SDK

SDK 패키지 최신 버전 확인처
Node.js @bootpay/backend-js 2.13.1 npm
Python bootpay-backend 2.8.1 PyPI
PHP bootpay/server-php 2.9.1 Packagist
Java io.github.bootpay:backend 3.6.0 Maven Central
Ruby bootpay 3.0.0 RubyGems
Go github.com/bootpay/backend-go/v2 v2.8.2 pkg.go.dev
.NET Bootpay 2.8.0 NuGet
버전을 직접 적는 SDK 만 챙기면 돼요

npm · pip · composer · go get · dotnet add 는 버전을 지정하지 않으면 언제나 최신을 받아요. 반면 Android · iOS · CDN · Java 는 설치 코드에 버전을 직접 쓰기 때문에 위 표를 보고 올려줘야 해요.

Ruby 는 3.0.0 부터 커머스 API 가 들어 있어요

BootpayStore 기반 예제는 bootpay 3.0.0 이상​​에서 동작해요. 2.x 에는 커머스 API 가 없어요.

예전 이름으로 쓰던 코드는 require 'bootpay-backend-ruby' 그대로 동작해요(호환 진입점 유지). 새로 붙이는 코드는 require 'bootpay' 를 쓰세요.

서버 인증 확인

커머스 API 는 프로젝트 키의 Basic 인증으로 바로 호출해요. 키가 연결된 프로젝트는 GET /v1/projects/me 로 확인할 수 있어요. 이 API 는 별도의 scope 가 필요하지 않지만, 응답에 서버 키와 비공개 키가 들어 있으므로 결과를 브라우저나 로그에 그대로 남기지 않아요.

GEThttps://api.bootapi.com/v1/projects/meBasic Auth
curl https://api.bootapi.com/v1/projects/me \
  -H "Authorization: Basic $(printf '%s:%s' "$BOOTPAY_COMMERCE_CLIENT_KEY" "$BOOTPAY_COMMERCE_SECRET_KEY" | base64)"bash

개발 환경은 주소를 https://dev-api.bootapi.com/v1/projects/me 로 바꿔요. 실제 서버 코드에서는 키를 서버 전용 환경 변수로 읽고, 필요한 필드만 확인해요. 응답 필드와 오류는 프로젝트 API를 봐요.

Ruby SDK 는 토큰이 없으면 Basic 인증을 자동 적용해요.

require 'bootpay'

commerce = BootpayStore::RestClient.new(client_key: '{client_key}', secret_key: '{secret_key}')
response = commerce.get_store
puts responseruby

기존 Bearer 연동에서만 POST /v1/request/token 을 사용해요. 토큰은 30분 동안 유효하며, 신규 연동에는 발급 단계가 필요 없어요. 서버 인증 · 기존 토큰 발급 API

함께 보기