전체 연동 여정

환경 설정부터 상품·고객·체크아웃·결제 확인·주문·배송·취소까지 순서대로 연동합니다.

한눈에

단계 할 일 메뉴 적용 조건 문서
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 그룹 고객 연결 후 그룹·구매 한도·통합 결제를 연결합니다 마켓플레이스

전체 플로우

흐름 시퀀스 문서
상품 등록 → 고객 연결 → 주문서 → 결제 확인 → 주문 관리 → 배송 → 취소·환불 주문 흐름
구독 구독 흐름

함께 보기