Bootpay 커머스 매뉴얼

주문·배송

주문 개요

결제가 끝난 뒤의 조회·취소·환불이 모두 주문을 기준으로 돌아요.

주문 준비·조회·배송 처리의 HTTP 필드와 오류는 주문 API, 취소·결제 승인은 주문 처리 API를 확인해요.

주문은 커머스 SDK의 중심 객체예요. 체크아웃에서 결제가 끝나면 주문이 생성되고, 이후 조회·취소·환불·웹훅 처리가 모두 주문을 기준으로 이어져요. API 호출에 넣는 값은 order_number 예요.

결제 SDK에서는 receipt_id가 중심이라면, 커머스 SDK에서는 주문이 운영의 중심이에요. 결제 결과는 주문 안에 들어오고, 서비스는 주문 상태를 보고 배송·권한·구독 접근을 결정해요. 구독 상품을 주문한 경우라면 여기서 계약·회차·해지 흐름으로 이어져요.

다만 프론트엔드 콜백만 믿고 주문을 확정하면 안 돼요. 결제 완료를 받으면 서버가 order_number 로 주문을 다시 조회해 금액·상품·고객을 대조하고, 취소·환불은 주문 상태와 결제 상태를 함께 보고 판단해요. 그래도 놓치는 상태 변경은 웹훅이 보정해요.

주문을 가리키는 값이 둘이에요

order_number(예: 25071182085082524116)는 조회·취소 API 에 넣는 값이고, order_id(24자리 ObjectId)는 내부 문서 ID 예요. 조회에 order_id 를 넣으면 ORDER_NOT_FOUND 가 돌아와요. 둘 다 저장해 두되 호출에는 order_number 를 써요.

개념 배경

결제 API와 커머스 API의 선택 기준은 블로그에서 의사결정 관점으로 다뤄요.

관리자에서 쓰는 법

개발 없이 부트페이 관리자에서 하는 순서는 블로그 주문 · 취소 처리 사용법 — 주문 확인하고 배송·취소 요청 처리하기에 정리했어요.

주문 흐름 한눈에

내가 하는 것, Bootpay가 하는 것

내가 하는 것

  • 장바구니 금액·상품·재고 검증
  • order_number 기준 주문 조회와 내부 주문 매핑
  • 배송, 서비스 권한, 구독 접근 같은 후속 처리
  • 취소 가능 여부 판단과 취소 요청
  • 웹훅 중복 처리와 내부 상태 보정

Bootpay가 알아서 하는 것

  • 체크아웃 결제 진입과 주문 객체 생성
  • 주문 상태·결제 상태 제공
  • 취소·환불 API와 결과 상태 제공
  • 주문·구독 이벤트 웹훅 발송

결제 API와 주문 API의 기준값

구분 결제 SDK 커머스 SDK
중심 ID receipt_id order_number
확인 대상 결제 영수증, 금액, 결제 상태 주문, 상품, 고객, 결제 상태
취소 기준 결제 취소 API 주문 취소·취소 요청 API
적합한 경우 자체 주문 시스템이 이미 있음 주문 운영까지 Bootpay 객체로 묶음

커머스에서도 실제 결제 검증은 중요해요. 다만 서비스 운영에서는 주문을 기준으로 배송·권한·취소 흐름을 이어가는 편이 자연스러워요.

주문 상태를 다룰 때 확인할 값

값 확인 이유
order_number 내부 주문 또는 장바구니와 연결하는 기준 (상세·웹훅에는 order_id 가 없어요)
price 서버가 계산한 금액과 일치하는지 확인
status 주문 완료·취소·대기 상태 판단
receipt_id 결제 상세 조회와 취소 추적 기준
user.user_id 고객 권한, 배송, CS 연결 기준
products 주문 상품·수량·옵션 확인

처음 붙일 때는 주문 상세을 먼저 구현하고, 그 다음 주문 조회, 주문 취소를 붙이면 돼요.

배송 흐름

실물 상품이 있는 주문은 결제가 끝난 뒤 이행 단계​​가 따로 흘러가요. 배송은 주문 전체가 아니라 발주(order_purchases) 단위​​로 움직여요 — 한 주문이 두 번에 나뉘어 나가면 운송장도 두 개예요.

단계 누가 문서
발주 확인·상품 준비 가맹점 발송처리
택배사·운송장 등록(발송 완료) 가맹점 발송처리
집화·이동·배송 완료 택배사 → Bootpay가 자동 수집 배송추적 조회
구매 확정 구매자 또는 자동 서버 API 없음 — 주문 목록의 purchase_confirmed_at 으로 확인

운송장을 넣는 순간부터 배송 추적이 자동으로 붙어요. 서비스 서버가 택배사를 따로 조회할 필요는 없고, 배송추적 조회만 읽으면 돼요.

상태가 두 축이에요

status는 가맹점이 처리한 단계​(발주 확인·발송 완료)고, d_ts는 택배사가 알려준 단계​(집화·배송 완료)예요. 둘은 따로 움직이고, 값은 커머스 Enum에서 확인해요.

배송 완료는 직접 넘기지 않아도 돼요

택배사가 배송 완료를 알려주면 발주 상태도 따라 넘어가요. 발송처리까지만 해두면 나머지는 자동이에요.

취소·환불 흐름

취소는 주문 운영에서 가장 사고가 많이 나는 구간이에요. 고객 요청, 운영자 승인, PG 환불, 내부 서비스 권한 해제를 같은 흐름으로 봐야 해요.

상황 먼저 볼 문서 서버가 할 일
바로 취소 가능한 주문 주문 취소 취소 요청 후 주문 상태 보정
고객 취소 요청 목록 확인 취소 요청 목록 대기 건을 운영 화면에 노출
운영자가 취소 승인 취소 요청 승인 환불 결과와 내부 상태 반영
운영자가 취소 거절 취소 요청 거절 거절 사유 저장과 고객 안내
고객이 취소 철회 취소 요청 철회 주문 진행 상태 복구
취소 API 호출 전 내부 상태를 먼저 확인해요

이미 배송이 시작됐거나 서비스 권한이 사용된 주문은 결제 취소만으로 운영 처리가 끝나지 않아요. 취소 가능 여부는 서비스 서버가 먼저 판단해야 해요.

구독 주문으로 이어지는 경우

구독 상품이 포함된 주문은 결제 이후 계약·회차·운영 흐름으로 이어져요.

  1. 체크아웃에서 구독 상품을 결제해요.
  2. 서버가 order_number로 주문을 조회하고 상품 유형을 확인해요.
  3. 구독 신청 또는 계약 상태를 확인해요.
  4. 승인·회차·정지·해지 처리는 구독 문서에서 이어가요.
단계 문서
구독 전체 흐름 이해 구독 개요
구독 신청과 승인 신청 관리
회차별 청구 확인 회차 조회
정지·재개·해지 구독 > 운영

함께 보기