커머스 SDK 소개 | Bootpay 커머스 매뉴얼

30초 판단

지금 상황	볼 문서
주문·상품·고객 시스템이 이미 있고, 결제창만 붙이면 돼요	결제 매뉴얼
쇼핑몰 백엔드를 새로 만들거나 줄이고 싶어요	이 매뉴얼
구독·링크페이·B2B 처럼 결제 이후 운영이 길어요	이 매뉴얼
우리 서비스에 카카오 알림톡을 붙이고 싶어요	알림톡 — 쇼핑몰 밖 서비스도 API로 연동해요

결제 SDK 는 결제를 성공시키는 도구예요. 커머스 SDK 는 결제 전후의 쇼핑몰 운영을 줄이는 도구예요.

무엇이 줄어드나

쇼핑몰은 화면만 보면 단순한데, 백엔드를 직접 짜면 이만큼이 필요해요.

Project
├── User                              고객 (개인정보 암호화)
│   └── UserWallet                    저장 결제수단·빌링키
├── Product                           상품
│   ├── ProductOption                 옵션 (색상·사이즈)
│   ├── ProductSnapshot               주문 시점 가격 고정
│   └── SubscriptionSetting           구독 정책 (주기·재시도·해지)
├── OrderPre                          결제 전 임시 주문 (31분 만료)
│   └── Order                         결제 완료 확정 주문
│       ├── OrderPurchase             판매자별 이행·배송 단위
│       └── OrderCancellationRequestHistory  취소·환불 이력
├── OrderSubscription                 구독 계약
│   └── OrderSubscriptionBill         회차별 과금
│       └── OrderSubscriptionTransaction  결제 실행
└── WebhookJob → WebhookLog           이벤트 발송·이력

엔티티 15개
+ 주문 상태머신 (상태 18종 — 결제 대기·진행·완료, 취소·반품·교환, 구독 분기)
+ 구독 상태머신 + 회차(Bill) 상태 — 서로 다른 두 체계
+ 결제 결과 서버 재검증
+ 웹훅 멱등 처리

// 1. 주문서를 연다
await BootpayCommerce.requestCheckout({
  client_key: CLIENT_KEY,
  request_id: draftId,
  price: 29900,
  products: [{ product_id: 'your-product-id', quantity: 1 }],
  user: { membership_type: 'guest', user_id: 'user_1234' },
  redirect_url: `${origin}/checkout/result`,
  extra: { open_type: 'redirect' },
})

// 2. 서버가 결과를 다시 확인한다
const order = await fetch(
  `https://api.bootapi.com/v1/orders/${orderNumber}`,
  { headers: { Authorization: `Basic ${auth}` } },
).then((r) => r.json())

if (order.price !== expectedPrice) throw new Error('금액 불일치')
if (order.status !== 'payment_completed') throw new Error('미결제')

// 3. 웹훅으로 상태를 맞춘다
//    order.done · order.cancelled · subscription.approved ...javascript

위 트리는 커머스 API 가 내부에서 관리하는 실제 모델이에요. 전체 구조는 데이터 모델에서 볼 수 있어요.

어디서 복잡해지나

직접 만들 때 예상보다 오래 걸리는 지점이에요.

처음 생각	실제로 챙겨야 하는 것
상품 하나 등록하면 돼요	옵션, 가격, 판매 상태, 노출 여부를 계속 맞춰야 해요
결제 성공하면 주문 완료예요	서버에서 금액·상태를 다시 검증하고 주문을 확정해야 해요
회원 정보만 저장하면 돼요	비회원, 그룹, 로그인 토큰, 구독 고객을 구분해야 해요
취소 버튼 하나면 돼요	취소 요청, 승인·거절, 환불, 서비스 비활성화 기준이 필요해요
구독은 매달 결제하면 돼요	신청, 승인, 회차, 일시정지, 재개, 해지를 상태로 관리해야 해요
주문 하나에 운송장 하나예요	판매자·창고가 나뉘면 발주 단위로 쪼개져요

커머스 SDK 는 이 기준을 처음부터 다시 설계하지 않게 해요. 상품을 등록하고, 고객을 식별하고, 체크아웃으로 주문을 열고, 결제 결과를 주문 상태로 이어가면 돼요.

결제 API 와 무엇이 다른가

구분	결제 API	커머스 API
중심	결제창 호출·승인·취소	상품·고객·주문 라이프사이클
주문 DB	서비스가 직접 구현	Bootpay 주문 객체와 API 를 사용
상품 정보	결제 요청마다 직접 전달	상품에 등록하고 재사용
고객 정보	결제 요청 데이터로 전달	고객 API·로그인 토큰으로 연결
조회 키	`receipt_id`	`order_number`

AI 에게 맡기기

Claude Code 같은 AI 에이전트를 쓴다면 채팅창에 한 줄이면 시작돼요.

https://github.com/bootpay/bootpay-mcp 참조해서 mcp 설치해주고, 커머스 연동해줘.

에이전트가 Bootpay MCP 를 먼저 설치하고, 그 도구로 문서와 예제를 읽어 SDK 설치부터 상품·주문·구독 코드까지 만들어요. MCP 서버 등록을 직접 하고 싶으면 AI 연동 가이드에서 봐요.

다음 단계

하고 싶은 일	다음 문서
어떤 기능이 있는지 훑어봐요	커머스 상품 둘러보기
전체 연동 순서를 보고 싶어요	전체 연동 여정
키 발급과 SDK 설치가 필요해요	환경 설정
코드부터 붙여봐요	체크아웃 빠르게 붙이기
엔드포인트별 요청·응답이 필요해요	v1 API 문서