어떤 기능이 자기 서비스에 필요한지 먼저 고르려면 커머스 상품 둘러보기를 봐요. 코드부터 붙이고 싶으면 체크아웃 빠르게 붙이기로 건너뛰어요.
한눈에
| 단계 | 할 일 | 메뉴 | 언제 |
|---|---|---|---|
| 0. 준비 | 연동키 발급·SDK 설치·서버 인증 | 시작하기 · 서버 연동 | 항상 |
| 1. 상품 등록 | 파는 것을 등록하고 product_id 받기 |
판매 준비 › 상품 | 항상 |
| 2. 고객 연결 | 우리 회원을 부트페이 고객과 잇기 | 판매 준비 › 고객 | 회원 주문일 때 |
| 3. 주문서 열기 | 금액을 정하고 주문서 띄우기 | 결제·주문 › 체크아웃 | 항상 |
| 4. 결제 확인 | 서버 재조회·웹훅으로 주문 확정 | 체크아웃 · 주문·배송 · 서버 연동 | 항상 |
| 5. 주문 관리 | 주문 목록·상세 화면 | 결제·주문 › 주문·배송 | 항상 |
| 6. 배송 | 운송장 등록·배송 추적 | 결제·주문 › 주문·배송 | 실물 상품일 때 |
| 7. 취소·환불 | 취소 요청·승인·거절 | 결제·주문 › 주문·배송 | 항상 |
링크페이·구독·알림톡·마켓플레이스는 이 흐름에서 갈라지거나 덧붙는 갈래예요. 흐름이 갈라지는 경우에서 어디가 바뀌는지 봐요.
이 여정이 맞나
고객이 상품을 골라 결제하는 서비스(쇼핑몰·예약 판매·구독 서비스)를 만들고, 결제 뒤 주문·배송·취소까지 한 번에 처리하려는 경우예요.
결제만 필요하고 주문 관리는 자체 구현이면 → 결제 SDK: 결제창 빠른 매뉴얼
결제만 붙일지, 커머스 SDK 까지 갈지의 판단은 결제만 vs 커머스 스코프 결정 를 먼저 봐요.
0준비
메뉴: 시작하기 · 서버 연동
- 커머스 연동키
client_key·secret_key를 발급하고 SDK 를 설치해요. 결제 SDK 의 연동키와 따로 받아요 → 환경설정 - 서버에서 커머스 API 를 Basic 인증으로 호출해요. 구매자 본인 API 는 회원 JWT 또는 엔드포인트가 허용하는
user_id도 필요해요 → 서버 인증 · 회원 JWT - 실제 경로·요청·응답은 v1 API 문서에서 확인해요. 인증 없이
GET /v1/docs를 열거나 API 주소에Accept: text/markdown을 보내도 같은 원본 문서를 읽을 수 있어요. - PG사·결제수단 활성화는 결제와 같은 프로젝트 설정을 써요 → 결제 매뉴얼 환경 설정
1상품 등록
메뉴: 판매 준비 › 상품
- 할 일: 파는 것을 부트페이에 등록하고
product_id를 받아요. 체크아웃은 이 ID와 수량으로 주문을 만들어요 - 문서: 상품 빠르게 붙이기 → 상품 생성
- 필수 값:
name,display_price— 나머지는 상품 개요에서 필요할 때 더해요 - 판매 상태: 품절·숨김·판매중지는 상태 변경으로 제어해요. 바꾸는 즉시 목록 조회 결과에 반영돼요
- 선택: 「이번 주 신상」 같은 묶음을 화면에 내보내려면 카테고리·진열을 더해요
- 실물 상품이면: 배송비는 상품이 아니라 배송비 정책이 정해요. 정책을 만들어 상품에 붙여 둬요 (메뉴는 주문·배송 › 배송)
상품 카테고리·정렬·노출 상태 설계는 상품 진열을 어떤 축으로 설계할까 를 참고해요.
2고객 연결
메뉴: 판매 준비 › 고객 — 비회원 주문만 받는다면 건너뛰어요
- 할 일: 우리 서비스 회원을 부트페이 고객과 이어, 주문과 구독을 같은 고객 기준으로 묶어요
- 순서: 중복 확인 → 고객 가입 → 로그인 토큰으로 주문서에 연결
- 관리: 고객 목록 · 프로필 수정
3주문서 열기
메뉴: 결제·주문 › 체크아웃
- 할 일: 장바구니를 결제 가능한 주문서로 바꿔 띄워요
- 순서:
- 결과: 결제가 끝나면
redirect_url로order_number와event가 돌아와요
상담·전화 주문처럼 링크만 보내 수납한다면 이 단계를 링크페이로 바꿔요. 상품을 등록하지 않아도 돼요.
4결제 확인
메뉴: 체크아웃 · 주문·배송 · 서버 연동
브라우저로 돌아온 event=done 만 믿고 주문을 확정하지 않아요. 서버가 한 번 더 확인해요.
- 결제 결과 조회 — 결과 화면에 보여 줄 값을 받아요. 이걸로 주문을 확정하지는 않아요
- 주문 상세 — 서버가
order_number로 다시 조회해 금액과 상태(payment_completed)를 확인하고 주문을 확정해요 - 결제 승인 — 분리 승인(
separately_confirmed)으로 연 주문이면 확인을 마친 뒤 여기서 승인해요 - 웹훅 설정 → 웹훅 처리 가이드 —
order.done·order.cancelled같은 이벤트로 놓친 상태를 보정해요 - 처리: 성공 → 주문 확정, 배송 준비 / 실패 → 장바구니 복원, 사용자 알림
5주문 관리
메뉴: 결제·주문 › 주문·배송
6배송
메뉴: 결제·주문 › 주문·배송 — 실물 상품일 때만
- 할 일: 운송장을 넣으면 배송 추적이 자동으로 붙어요
- 문서: 발송처리 → 배송추적 조회
- 배송은 주문이 아니라 발주(
order_purchases) 단위로 움직여요. 한 주문이 두 번에 나가면 운송장도 두 개예요 - 구매 확정은 서버 API 가 없어요. 주문 목록의
purchase_confirmed_at으로 확인해요
7취소·환불
메뉴: 결제·주문 › 주문·배송
커머스 취소는 4단 상태 전이예요. 단순 취소가 아니에요.
- 할 일: 고객 취소 요청 → 관리자 승인/거절 → 환불 회수 → 조회
- 문서: 주문 취소 → 취소 목록 → 취소 승인 또는 취소 거절
- 고객이 요청을 거둬들이면 취소 철회
- 배송이 시작됐거나 서비스 권한이 이미 쓰인 주문은 결제 취소만으로 끝나지 않아요. 취소 가능 여부는 서버가 먼저 판단해요
취소·환불 정책·승인 구조·회수 범위 설계는 주문 취소 정책 설계 를 봐요.
흐름이 갈라지는 경우
| 이런 서비스면 | 여정에서 바뀌는 곳 | 메뉴 |
|---|---|---|
| 주문서 없이 링크로 수납해요 | 3단계를 링크 생성으로 바꿔요. 상품 등록은 없어도 돼요 | 결제·주문 › 링크페이 |
| 매달 자동으로 청구해요 | 1단계에서 구독 설정을 붙인 상품을 만들고, 결제 뒤 계약·회차 운영이 이어져요 | 구독 → 구독 계약 → 구독 운영 |
| 결제·배송 안내를 카카오로 보내요 | 4~7단계에 알림톡 발송을 더해요 | 알림톡 설정 → 알림톡 발송·운영 |
| 거래처·부서 단위로 사요 (B2B) | 2단계 뒤에 그룹·구매 한도·통합 결제를 더해요 | 확장·참고 › 마켓플레이스 |
구독은 유형부터 정하면 빨라요 — 유형 선택 가이드 · 구독 빠르게 붙이기
전체 플로우
상품 등록 → 고객 연결 → 주문서 → 결제 확인 → 주문 관리 → 배송 → 취소·환불 시퀀스 다이어그램은 주문 흐름, 구독은 구독 흐름에서 봐요.
다음 단계
- 코드부터 붙이기 → 체크아웃 빠르게 붙이기
- 키 발급·SDK 설치 → 환경설정
- 전체 API 를 한 표로 → API 인덱스, 엔드포인트별 계약은 v1 API 문서
- 문제 대응 FAQ → FAQ