환경 설정부터 상품·고객·체크아웃·결제 확인·주문·배송·취소까지 순서대로 연동합니다.
한눈에
| 단계 |
할 일 |
메뉴 |
적용 조건 |
문서 |
| 0. 준비 |
연동키 발급·SDK 설치·서버 인증 |
시작하기 · 서버 연동 |
항상 |
환경설정 · 서버 인증 |
| 1. 상품 등록 |
상품을 등록하고 product_id 를 받습니다 |
판매 준비 › 상품 |
항상 |
상품 등록 |
| 2. 고객 연결 |
서비스 회원을 부트페이 고객에 연결합니다 |
판매 준비 › 고객 |
회원 주문일 때 |
중복 확인 → 고객 가입 → 로그인 토큰 |
| 3. 주문서 열기 |
금액을 정하고 주문서를 호출합니다 |
결제·주문 › 체크아웃 |
항상 |
주문 준비 → 주문서 요청 |
| 4. 결제 확인 |
서버 재조회·웹훅으로 주문을 확정합니다 |
체크아웃 · 주문·배송 · 서버 연동 |
항상 |
결제 결과 조회 · 주문 상세 · 결제 승인 |
| 5. 주문 관리 |
관리자·주문내역 화면에 주문을 표시합니다 |
결제·주문 › 주문·배송 |
항상 |
주문 목록 · 주문 상세 |
| 6. 배송 |
운송장 등록·배송 추적을 연동합니다 |
결제·주문 › 주문·배송 |
실물 상품일 때 |
발송처리 → 배송추적 조회 |
| 7. 취소·환불 |
취소 요청·승인·거절·환불을 처리합니다 |
결제·주문 › 주문·배송 |
항상 |
주문 취소 → 취소 목록 → 취소 승인 또는 취소 거절 |
개발 전 정할 값
| 단계 |
값·조건 |
구현 내용 |
| 준비 |
client_key · secret_key |
커머스 연동키는 결제 SDK 연동키와 별도로 발급합니다 |
| 준비 |
Basic 인증·회원 JWT |
서버에서 Basic 인증으로 커머스 API 를 호출합니다. 구매자 본인 API 는 회원 JWT 또는 엔드포인트가 허용하는 user_id 도 필요합니다. 회원 JWT에서 확인합니다 |
| 준비 |
API 문서 |
실제 경로·요청·응답은 v1 API 문서에서 확인합니다. 인증 없이 GET /v1/docs 를 호출하거나 API 주소에 Accept: text/markdown 을 보내도 같은 원본 문서를 읽을 수 있습니다 |
| 준비 |
PG사·결제수단 활성화 |
결제와 같은 프로젝트 설정을 사용합니다. 결제 매뉴얼 환경 설정에서 확인합니다 |
| 상품 |
name · display_price |
필수 값입니다. 추가 값은 상품 개요에서 확인합니다 |
| 상품 |
판매·노출 상태 |
품절·숨김·판매중지는 상태 변경으로 제어하며 변경 즉시 목록 조회 결과에 반영됩니다 |
| 상품 |
카테고리·진열 |
카테고리·진열로 상품 묶음을 표시합니다 |
| 상품 |
배송비 정책 |
실물 상품의 배송비는 상품이 아니라 배송비 정책이 결정합니다. 정책을 만들어 상품에 연결합니다 |
| 고객 |
회원·비회원 |
회원을 연결하면 주문과 구독을 같은 고객 기준으로 관리합니다. 비회원 주문만 받으면 고객 연결 단계를 생략합니다 |
| 고객 |
고객 관리 |
고객 목록 · 프로필 수정을 연동합니다 |
| 주문서 |
주문 준비 (선택) |
서버가 배송비를 포함한 금액을 확정하고 order_number 를 받습니다. 서버에서 금액 위변조를 방지합니다 |
| 주문서 |
BootpayCommerce.requestCheckout |
프론트엔드에서 주문서를 호출합니다. 결제 후 redirect_url 로 order_number 와 event 가 반환됩니다 |
| 결제 확인 |
event=done |
브라우저 결과만으로 주문을 확정하지 않습니다. 결제 결과 조회는 결과 화면 표시용이며 주문 확정에 사용하지 않습니다 |
| 결제 확인 |
order_number · payment_completed |
서버에서 주문 상세를 다시 조회하고 금액과 상태를 확인한 후 주문을 확정합니다 |
| 결제 확인 |
separately_confirmed |
분리 승인 주문은 검증을 마친 뒤 결제 승인을 호출합니다 |
| 결제 확인 |
order.done · order.cancelled |
웹훅 설정 → 웹훅 처리 가이드에 따라 누락된 상태를 보정합니다 |
| 결제 확인 |
성공·실패 처리 |
성공 시 주문 확정·배송 준비, 실패 시 장바구니 복원·사용자 알림을 처리합니다 |
| 주문 관리 |
조회 키 |
API 호출에는 order_id 가 아니라 order_number 를 사용합니다 |
| 배송 |
order_purchases |
배송은 주문이 아니라 발주 단위로 처리합니다. 한 주문이 두 번에 나가면 운송장도 두 개입니다 |
| 배송 |
purchase_confirmed_at |
구매 확정 서버 API 는 없습니다. 주문 목록에서 구매 확정 여부를 확인합니다 |
| 취소·환불 |
4단 상태 전이 |
고객 취소 요청 → 관리자 승인/거절 → 환불 회수 → 조회 순서로 처리합니다 |
| 취소·환불 |
취소 철회 |
고객이 요청을 거두면 취소 철회를 호출합니다 |
| 취소·환불 |
배송·사용 여부 |
배송이 시작됐거나 서비스 권한이 이미 사용된 주문은 결제 취소만으로 처리되지 않습니다. 서버에서 취소 가능 여부를 먼저 판단합니다 |
흐름이 갈라지는 경우
| 연동 기능 |
구현 흐름 |
문서 |
| 링크페이 |
주문서 호출 대신 링크를 생성합니다. 상품 등록은 필수가 아닙니다 |
링크페이 |
| 구독 |
구독 설정을 연결한 상품을 등록하고 결제 후 계약·회차를 관리합니다 |
구독 → 구독 계약 → 구독 운영 |
| 알림톡 |
결제 확인·주문·배송·취소 단계에 알림톡 발송을 연결합니다 |
알림톡 설정 → 알림톡 발송·운영 |
| B2B 그룹 |
고객 연결 후 그룹·구매 한도·통합 결제를 연결합니다 |
마켓플레이스 |
전체 플로우
| 흐름 |
시퀀스 문서 |
| 상품 등록 → 고객 연결 → 주문서 → 결제 확인 → 주문 관리 → 배송 → 취소·환불 |
주문 흐름 |
| 구독 |
구독 흐름 |