이 문서는 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
npm install @bootpay/client-jsbash<script src="https://js.bootpay.co.kr/bootpay-5.3.1.min.js"></script>htmlimplementation 'io.github.bootpay:android:5.2.0'pod 'Bootpay', '~> 5.1.1'rubyflutter pub add bootpaybashnpm install react-native-bootpay-apibash서버 SDK
npm install @bootpay/backend-jsbashpip install bootpay-backendbashcomposer require bootpay/server-phpbashimplementation 'io.github.bootpay:backend:3.5.0'gem install bootpay-backend-ruby --prebashgo get github.com/bootpay/backend-go/v2bashdotnet add package Bootpaybash최신 버전
각 SDK 의 최신 버전이에요. 기준일은 2026-08-26 이고, 확인처 링크에서 항상 최신 값을 볼 수 있어요.
클라이언트 SDK
| SDK | 패키지 | 최신 버전 | 확인처 |
|---|---|---|---|
| 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.0 | Maven Central |
| iOS · Swift | Bootpay |
5.1.1 | CocoaPods |
| Flutter · Dart | bootpay |
5.3.1 | pub.dev |
| React Native | react-native-bootpay-api |
13.15.0 | npm |
서버 SDK
| SDK | 패키지 | 최신 버전 | 확인처 |
|---|---|---|---|
| Node.js | @bootpay/backend-js |
2.12.0 | npm |
| Python | bootpay-backend |
2.7.0 | PyPI |
| PHP | bootpay/server-php |
2.8.0 | Packagist |
| Java | io.github.bootpay:backend |
3.5.0 | Maven Central |
| Ruby | bootpay-backend-ruby |
3.0.0.pre.alpha.3 | RubyGems |
| Go | github.com/bootpay/backend-go/v2 |
v2.7.0 | pkg.go.dev |
| .NET | Bootpay |
2.7.0 | NuGet |
npm · pip · composer · go get · dotnet add 는 버전을 지정하지 않으면 언제나 최신을 받아요. 반면 Android · iOS · CDN · Java 는 설치 코드에 버전을 직접 쓰기 때문에 위 표를 보고 올려줘야 해요.
이 매뉴얼의 Ruby 예제는 BootpayStore 기반 3.0 계열을 사용해요. --pre 없이 설치하면 커머스 API 가 들어있지 않은 2.0.5 가 받아져서 예제가 동작하지 않아요.
서버 인증 확인
SDK 설치 후에는 커머스 토큰 발급으로 서버 인증을 먼저 확인해요. 토큰 발급은 백엔드에서만 실행해야 해요.
https://api.bootapi.com/v1/request/tokenCommerce Client Key + Secret Key인증 정보는 Authorization 헤더로 보내요. 요청 본문은 필요 없어요.
Ruby SDK 는 토큰이 없으면 client_key/secret_key 로 Basic 인증을 자동 적용해요. 아래 예제처럼 클라이언트만 만들면 바로 API 를 호출할 수 있어요.
require 'bootpay-backend-ruby'
commerce = BootpayStore::RestClient.new(client_key: '{client_key}', secret_key: '{secret_key}')
response = commerce.get_store # 토큰 발급 없이 바로 호출돼요
puts responseruby토큰 발급 API 자체는 서버 인증을 눈으로 확인하거나 다른 언어 SDK 를 쓸 때 참고해요.
| 위치 | 값 | 필수 | 설명 |
|---|---|---|---|
Header |
Authorization: Basic {base64(client_key:secret_key)} | 필수 | 커머스 Client Key와 Secret Key를 :로 이어 Base64 인코딩해요 |
헤더 없이 호출하면 요청 본문으로 인증해요. 이때 파라미터 이름은 client_key/secret_key가 아니라 아래와 같아요.
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| server_key | String | Y | 프로젝트 Server Key |
| private_key | String | Y | 프로젝트 Private Key |
const auth = Buffer.from(
`${process.env.BOOTPAY_COMMERCE_CLIENT_KEY}:${process.env.BOOTPAY_COMMERCE_SECRET_KEY}`
).toString('base64')
const response = await fetch('https://api.bootapi.com/v1/request/token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Basic ${auth}`,
},
})
const token = await response.json()
console.log(token.access_token)javascriptimport os
import requests
response = requests.post(
'https://api.bootapi.com/v1/request/token',
auth=(os.environ['BOOTPAY_COMMERCE_CLIENT_KEY'], os.environ['BOOTPAY_COMMERCE_SECRET_KEY']),
)
print(response.json()['access_token'])python$auth = base64_encode(getenv('BOOTPAY_COMMERCE_CLIENT_KEY') . ':' . getenv('BOOTPAY_COMMERCE_SECRET_KEY'));
$response = file_get_contents('https://api.bootapi.com/v1/request/token', false, stream_context_create([
'http' => [
'method' => 'POST',
'header' => "Content-Type: application/json\r\nAuthorization: Basic {$auth}\r\n",
],
]));
$token = json_decode($response, true);
echo $token['access_token'];phpimport java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
HttpClient client = HttpClient.newHttpClient();
String auth = Base64.getEncoder().encodeToString(
(System.getenv("BOOTPAY_COMMERCE_CLIENT_KEY") + ":" + System.getenv("BOOTPAY_COMMERCE_SECRET_KEY"))
.getBytes(StandardCharsets.UTF_8));
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.bootapi.com/v1/request/token"))
.header("Content-Type", "application/json")
.header("Authorization", "Basic " + auth)
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());javarequire 'net/http'
require 'json'
uri = URI('https://api.bootapi.com/v1/request/token')
request = Net::HTTP::Post.new(uri, 'Content-Type' => 'application/json')
request.basic_auth(ENV.fetch('BOOTPAY_COMMERCE_CLIENT_KEY'), ENV.fetch('BOOTPAY_COMMERCE_SECRET_KEY'))
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body)['access_token']rubyreq, _ := http.NewRequest("POST", "https://api.bootapi.com/v1/request/token", nil)
req.SetBasicAuth(os.Getenv("BOOTPAY_COMMERCE_CLIENT_KEY"), os.Getenv("BOOTPAY_COMMERCE_SECRET_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))gousing var client = new HttpClient();
var auth = Convert.ToBase64String(Encoding.UTF8.GetBytes(
$"{Environment.GetEnvironmentVariable("BOOTPAY_COMMERCE_CLIENT_KEY")}:{Environment.GetEnvironmentVariable("BOOTPAY_COMMERCE_SECRET_KEY")}"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", auth);
var response = await client.PostAsync("https://api.bootapi.com/v1/request/token", null);
Console.WriteLine(await response.Content.ReadAsStringAsync());csharp인증 흐름과 토큰 갱신 전략은 서버 인증에서 더 자세히 다뤄요.
다음 단계
| 상황 | 다음 문서 |
|---|---|
| 첫 쇼핑몰 흐름을 붙여요 | 체크아웃 빠른 매뉴얼 |
| 상품부터 등록해요 | 카탈로그 이해하기 |
| 주문 조회·취소를 붙여요 | 주문 이해하기 |
| 구독 상품을 운영해요 | 구독 개요 |
| 결제 설정이 막힌다 | 결제 매뉴얼 환경 설정 |
