2026년 5월 19일

둘러보기

주문 관리 연동

2026년 5월 19일

주문 상태 전이와 취소 운영을 서비스 기준으로 고정해요.

결제 이후의 주문 상태를 서비스 운영 기준으로 안정적으로 굴리기 위한 여정이에요.

이 문서는 누구에게 맞나

체크아웃은 이미 붙였거나 곧 붙일 예정이고, 그 뒤에 이어지는 주문 조회·상태 전이·취소·환불·운영 리포팅을 제대로 설계하려는 개발자용이에요. 관리자 화면, 고객 주문 내역, CS 대응 기준이 모두 주문 엔티티 하나에 묶이는 팀에 맞아요.

다음이면 다른 문서로 가요.

쇼핑몰 체크아웃 통합이 주목적 이면 → 쇼핑몰 체크아웃
구독 갱신 주문 이면 → 구독 결제
결제 링크 발송 운영 이면 → 링크페이

주문은 결제 성공 한 번으로 끝나지 않아요. 상태 전이, 승인, 환불, 대사 기준을 먼저 정해야 해요.

주문 취소 정책 설계 — 요청·승인·거절 구조를 왜 분리해야 하는지 설명해요.
결제만 붙이면 되나요, 주문까지 해야 하나요? — 주문까지 가져갈 때 얻는 운영 이점을 정리해요.

준비

application_id / private_key — 결제 SDK의 연동키 가 canonical
서버 SDK 설치 → 환경설정
주문 상태 enum, 내부 주문 번호, 웹훅 idempotency 키 설계

단계 1: 주문 DB를 설계해요

할 일: 주문, 주문 아이템, 취소 요청, 상태 이력 테이블 구조를 먼저 잡아요.
API:
필수 값: order_id, user_id, status, paid_at

단계 2: 주문을 생성하고 조회해요

할 일: 체크아웃 또는 링크페이 완료 뒤 주문을 생성하고 목록·상세를 조회 가능하게 만들어요.
API:
필수 값: product_id, quantity, price

단계 3: 주문 상태 전이를 분리해요

할 일: pending → paid → fulfilled 와 같은 정상 흐름과 취소 요청 흐름을 다른 상태 집합으로 관리해요.
API:
- 주문 상세
- 주문 목록
필수 값: status, updated_at, operator_id

단계 4: 취소·환불 플로우를 붙여요

할 일: 고객 요청, 관리자 승인·거절, 철회, 취소 목록 추적을 각각 API 단위로 연결해요.
API:
필수 값: cancel_reason, approved_at

단계 5: 분석·리포팅과 운영 검증을 붙여요

할 일: 웹훅, 주문 목록, 취소 로그를 한 화면에서 맞춰 보고 일치 여부를 검증해요.
API:
필수 값: event, receipt_id, order_id

완료 후 체크

주문 목록과 주문 상세가 같은 상태 값을 보여줘요.
결제 성공 웹훅이 들어오면 주문이 중복 생성되지 않아요.
취소 요청과 취소 완료를 다른 상태로 추적해요.
운영팀이 주문 상태와 환불 이력을 같은 기준 ID로 찾을 수 있어요.

관련 문서