주문서 호출
Commerce SDK를 사용하여 구독/요금제 결제를 쉽게 구현하세요.
예제 사이트: paypg.kr에서 주문서 동작을 직접 확인해보세요.
Commerce SDK는 서비스의 상품, 구독 결제 등을 손쉽게 구현할 수 있습니다. 상품 등록부터 주문서 발행, 구독 관리까지 모든 과정을 지원합니다.
1
상품 등록 (관리자)
Admin
Commerce SDK를 사용하기 전에, 먼저 부트페이 관리자에서 판매할 상품을 등록해야 합니다.
상품 등록, 가격 설정, 구독 옵션 등 상세한 설정은 부트페이 관리자에서 진행하세요.
상품 등록 시 필요한 정보
상품명사용자에게 표시될 상품 이름가격상품 가격 (단건/구독 가격)구독 설정구독 상품인 경우 구독 정책 설정 (구독주기/환불 등)
상품 등록이 완료되면
product_id가 발급됩니다. 이 ID를 사용하여 결제를 요청합니다.2
주문 미리 생성 (옵션)
Server
선택
주문서 요청 전에 가맹점 내부 서버에서 먼저 주문을 생성하는 것을 권장합니다.
권장 사항: 내부 서버에서 주문을 먼저 생성하면 주문 실패, 결제 취소 등의 상황을 체계적으로 관리할 수 있습니다.
왜 내부 서버에서 먼저 생성하나요?
주문 관리결제 실패/취소 시에도 주문 이력을 추적할 수 있음데이터 일관성가맹점 DB와 부트페이 간 데이터 동기화 용이비즈니스 로직재고 확인, 쿠폰 적용, 배송비 계산 등 처리 가능
할인/프로모션 적용이 필요한 경우
기존 상품 가격에서 프로모션, 쿠폰, 등급별 할인을 적용하려면 부트페이 주문서 API를 호출하세요.
할인 적용: 부트페이 주문서 API로 주문을 미리 생성하고, 할인된 가격을 설정할 수 있습니다.
부트페이 주문 생성 API 파라미터
products상품 목록 (product_id, quantity 등)price할인이 적용된 최종 결제 금액user구매자 정보
할인 적용
request_id부트페이에서 발급한 주문 요청 ID - 주문서 요청 시 사용
부트페이 주문 생성 API를 사용한 경우, 주문서 요청 시
request_id를 반드시 전달해야 합니다.3
주문서 요청하기
Client
서버에서 받은 주문 정보로 BootpayCommerce.requestCheckout()를 호출하여 결제 페이지를 표시합니다.
결제 흐름: 주문 생성(order_id 발급) → 주문서 요청 → 결제 진행 → redirect_url 이동
필수 파라미터
client_keyCommerce 클라이언트 키name주문명 (예: "Professional 플랜")price서버에서 계산한 결제 금액redirect_url결제 완료 후 이동할 URL
할인 적용 시 필수 파라미터
할인/프로모션을 적용하려면 주문서 API로 미리 생성한 request_id를 함께 전달해야 합니다.
request_id주문서 API 호출 시 발급받은 주문 요청 ID (할인 정보 포함)
request_id를 전달하면 주문서 API에서 설정한 할인 가격이 자동으로 적용됩니다.products 배열
구독할 상품 정보를 배열로 전달합니다.
product_idCommerce에 등록된 상품 IDduration구독 기간 (-1은 무기한)quantity수량
user 객체
membership_type회원 유형 (guest또는member)user_id가맹점의 사용자 고유 IDname, phone, email사용자 정보
4
결제 완료 처리
Client
requestCheckout()가 완료되면 redirect_url로 이동하며, order_number가 URL 파라미터로 전달됩니다.
리다이렉트 URL 예시: https://example.com/result?order_number=ORDER_123&event=done
클라이언트에서 받은 결제 정보만으로 주문을 완료하지 마세요. 반드시 서버에서 검증 후 처리해야 합니다.
URL 파라미터
order_numberCommerce 주문 고유 번호 (서버 검증에 사용)event결제 결과 이벤트 (done,cancel,error)
5
서버에서 결제 검증
Server
서버에서 order_number로 Commerce API를 호출하여 실제 주문 정보를 조회하고, 결제 상태와 금액을 검증합니다.
Commerce API 엔드포인트: GET /v1/orders/{order_number}
검증 절차
1. 액세스 토큰 발급Commerce API 토큰 발급 (Basic Auth)2. 주문 정보 조회GET /v1/orders/{order_number}3. 결제 상태 확인status, receipt_status 검증
Commerce API 응답 주요 필드
status주문 상태 (order_completed,subscription_request_completed등)price결제 금액order_subscriptions구독 정보 (구독 상품인 경우)
검증 결과 처리
결제 완료: status가 완료 상태이면 주문을 확정하고 구독을 활성화합니다.
결제 실패/취소: status가 실패 또는 취소 상태이면 사용자에게 결과를 안내합니다.
고급 기능
주문 미리 생성으로 할인 적용
부트페이 주문 생성 API를 호출하여 할인된 가격으로 주문을 미리 생성할 수 있습니다.
활용 예시: 연간 결제 20% 할인, 프로모션 코드 적용, VIP 고객 특별 할인 등
server.js - 부트페이 주문 생성 API 호출
const { Bootpay } = require('@bootpay/backend-js')
app.post('/api/orders/create', async (req, res) => {
const { products, user, promotion_code } = req.body
// 할인 가격 계산
let finalPrice = calculateDiscountPrice(products, promotion_code)
// 부트페이 주문 생성 API 호출
await Bootpay.getAccessToken()
const order = await Bootpay.createOrder({
products: products,
price: finalPrice, // 할인 적용된 가격
user: user
})
res.json({
success: true,
request_id: order.request_id // 주문서 요청 시 사용
})
})주문서 요청 시
request_id를 전달하면 미리 생성한 주문 정보(할인 가격 포함)가 적용됩니다.extra 옵션
주문서 요청 시 extra 객체로 전달하는 옵션입니다.
| separately_confirmed | 분리 승인 모드 (true 시 별도 승인 필요) |
| create_order_immediately | 즉시 주문 생성 여부 |
metadata 활용
결제에 추가 정보를 저장할 수 있습니다.
예시
metadata: {
order_id: 'ORDER_123',
plan_key: 'pro',
billing_type: '연간',
promotion_code: 'SUMMER2024'
}
환경 설정
개발/스테이지/운영 환경을 설정할 수 있습니다.
예시
// 환경 설정 (SDK 초기화 전에 호출)
BootpayCommerce.setEnvironmentMode('development') // 테스트
BootpayCommerce.setEnvironmentMode('stage') // 스테이지
BootpayCommerce.setEnvironmentMode('production') // 운영
