이 문서는 커머스 체크아웃을 가장 짧게 붙이는 매뉴얼이에요. 전체 파라미터, 할인, 배송비, 프로모션은 주문서 요청에서 더 자세히 다뤄요.
핵심 요약
- 먼저 관리자 또는 API로 상품을 등록하고
product_id를 확보해요. - 프론트엔드는 상품 ID와 수량으로 체크아웃을 열어요.
- 결제 결과를 받으면 서버가
order_id로 주문을 다시 조회해 검증해요. - 주문·구독 상태 변경은 웹훅으로 한 번 더 보정해요.
내가 하는 것
- 상품 등록 또는 기존 상품 ID 매핑
- 장바구니 금액·수량 검증
- 서버에서
order_id기준 주문 조회 - 웹훅 중복 처리와 주문 상태 저장
Bootpay가 알아서 하는 것
- 주문서 UI와 결제 진입
- 결제 처리와 주문 객체 생성
- 주문·취소·구독 이벤트 웹훅 발송
STEP 1. 상품을 준비해요
Bootpay 관리자 → 상품 관리에서 상품을 등록하고 product_id를 받아요.
API로 등록하려면 상품 등록을 사용해요. 기존 상품 DB가 있으면 내부 상품 ID와 Bootpay product_id를 함께 저장해 두면 이후 주문 검증이 쉬워져요.
STEP 2. 체크아웃을 열어요
아래 코드는 최소 흐름만 보여줘요. 실제 서비스에서는 서버에서 장바구니 금액과 재고를 먼저 검증하고, 검증된 상품 ID와 수량만 체크아웃에 넘겨요.
import { BootpayCommerce } from '@bootpay/commerce-js'
const CLIENT_KEY = 'your-client-key'
BootpayCommerce.checkout({
clientKey: CLIENT_KEY,
items: [
{ product_id: 'your-product-id', qty: 1 },
],
onDone: async (data) => {
// 결제 성공 신호만으로 주문을 확정하지 않아요.
// 서버에서 order_id로 주문을 다시 조회하고 금액·상태를 검증해요.
await verifyOrder(data.order_id)
},
onCancel: (data) => {
console.log('결제 취소:', data)
},
onError: (data) => {
console.error('결제 실패:', data)
},
})javascript클라이언트 콜백만 믿으면 안 돼요
onDone은 사용자의 브라우저나 앱에서 받은 신호예요. 서버가 주문 조회 API와 웹훅으로 같은 결과를 확인한 뒤 주문 상태를 바꿔야 해요.
STEP 3. 서버에서 주문을 검증해요
서버는 커머스 토큰을 사용해 주문을 조회하고, 내부 주문 기준과 비교해요.
const response = await fetch(`https://api.bootapi.com/v1/orders/${orderId}`, {
headers: {
Authorization: `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
})
const order = await response.json()
if (order.price !== expectedPrice) {
throw new Error('주문 금액이 일치하지 않아요')
}
if (order.status !== 'done') {
throw new Error('결제 완료 주문이 아니에요')
}
await markOrderPaid(order.order_id)javascriptimport requests
response = requests.get(
f'https://api.bootapi.com/v1/orders/{order_id}',
headers={
'Authorization': f'Bearer {access_token}',
'Content-Type': 'application/json',
},
)
order = response.json()
if order['price'] != expected_price:
raise ValueError('주문 금액이 일치하지 않아요')
if order['status'] != 'done':
raise ValueError('결제 완료 주문이 아니에요')
mark_order_paid(order['order_id'])pythonSTEP 4. 웹훅으로 한 번 더 맞춰요
주문 상태가 바뀌면 웹훅으로 알림을 받아요.
| 이벤트 | 시점 | 서버가 할 일 |
|---|---|---|
order.done |
결제 완료 | 주문 완료 처리 또는 서비스 활성화 |
order.cancelled |
주문 취소 | 환불·서비스 비활성화 처리 |
subscription.approved |
구독 시작 | 구독 권한 활성화 |
subscription.terminated |
구독 종료 | 구독 권한 해제 |
웹훅 설정은 웹훅 설정, 이벤트별 처리 기준은 웹훅 처리 가이드를 이어서 확인해요.