주문서 요청

Commerce SDK를 사용하여 구독/요금제 결제를 쉽게 구현하세요.

예제 사이트: paypg.kr에서 주문서 동작을 직접 확인해보세요.|GitHub 예제

Commerce SDK는 서비스의 상품, 구독 결제 등을 손쉽게 구현할 수 있습니다. 상품 등록부터 주문서 발행, 구독 관리까지 모든 과정을 지원합니다.

상품 등록 (관리자)

Admin

Commerce SDK를 사용하기 전에, 먼저 부트페이 관리자에서 판매할 상품을 등록해야 합니다.

상품 등록, 가격 설정, 구독 옵션 등 상세한 설정은 부트페이 관리자에서 진행하세요.

상품 등록 시 필요한 정보

상품명사용자에게 표시될 상품 이름
가격상품 가격 (단건/구독 가격)
구독 설정구독 상품인 경우 구독 정책 설정 (구독주기/환불 등)

상품 등록이 완료되면 product_id가 발급됩니다. 이 ID를 사용하여 결제를 요청합니다.

청구서 미리 생성 (옵션)

Server

선택

할인/프로모션 적용이 필요한 경우, 서버에서 먼저 commerce.invoice.create()를 호출하여 invoice_id를 발급받습니다.

서버 SDK는 invoice.create(), 클라이언트 SDK는 requestCheckout()을 사용합니다. 메서드명이 다릅니다.

서버 vs 클라이언트 SDK 차이

구분	서버 (Backend SDK)	클라이언트 (Frontend SDK)
메서드	`commerce.invoice.create()`	`BootpayCommerce.requestCheckout()`
목적	청구서 생성, `invoice_id` 발급	결제창 표시
필수 여부	선택 (할인 적용 시)	필수

서버에서 청구서 생성 (할인 적용)

서버에서 commerce.invoice.create()를 호출하면 invoice_id가 반환됩니다.

price할인이 적용된 최종 결제 금액
products상품 목록 (product_id, quantity 등)
user구매자 정보

반환된 invoice_id를 클라이언트에 전달하세요.

클라이언트에서 invoice_id 사용

클라이언트에서 BootpayCommerce.requestCheckout() 호출 시 invoice_id를 함께 전달하면, 서버에서 설정한 할인 가격이 적용됩니다.

invoice_id를 전달하지 않으면 상품 원가로 결제됩니다.

주문서 요청하기

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에 등록된 상품 ID
duration구독 기간 (-1은 무기한)
quantity수량

user 객체

membership_type회원 유형 (guest 또는 member)
user_id가맹점의 사용자 고유 ID
name, phone, email사용자 정보

결제 완료 처리

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)

서버에서 결제 검증

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가 실패 또는 취소 상태이면 사용자에게 결과를 안내합니다.

고급 기능

청구서 미리 생성으로 할인 적용

부트페이 Commerce API의 invoice.create()를 호출하여 할인된 가격으로 청구서를 미리 생성할 수 있습니다.

활용 예시: 연간 결제 20% 할인, 프로모션 코드 적용, VIP 고객 특별 할인 등

server.js - 부트페이 청구서 생성 API 호출

const { BootpayCommerce } = require('@bootpay/backend-js')

const commerce = new BootpayCommerce({
  client_key: 'xxx',
  secret_key: 'yyy',
  mode: 'production'
})

app.post('/api/invoices/create', async (req, res) => {
  const { products, user, promotion_code } = req.body

  // 할인 가격 계산
  let finalPrice = calculateDiscountPrice(products, promotion_code)

  // 부트페이 청구서 생성 API 호출
  await commerce.getAccessToken()
  const invoice = await commerce.invoice.create({
    products: products,
    price: finalPrice,  // 할인 적용된 가격
    user: user
  })

  res.json({
    success: true,
    invoice_id: invoice.data.invoice_id  // 클라이언트에서 사용
  })
})

클라이언트에서 requestCheckout() 호출 시 invoice_id를 전달하면 미리 생성한 청구서 정보(할인 가격 포함)가 적용됩니다.

extra 옵션

주문서 요청 시 extra 객체로 전달하는 옵션입니다.

separately_confirmed	분리 승인 모드 (`true` 시 별도 승인 필요)
create_order_immediately	즉시 주문 생성 여부

metadata 활용

결제에 추가 정보를 저장할 수 있습니다.

예시

metadata: {
  order_id: 'ORDER_123',
  plan_key: 'pro',
  billing_type: '연간',
  promotion_code: 'SUMMER2024'
}

클라이언트

서버

설치 방식