핵심 요약
- 결제 API만 쓰면 결제 성공 이후 주문 생성·상태 전이·취소·환불 정합성을 전부 우리 서버가 책임져요. 웹훅 수신 로직, 상태 기계, 회계 대사까지 직접 짜요.
- 커머스 API로 넘기면 주문이 자동 생성되고, 주문 조회·부분 취소·환불·웹훅까지 PG가 관리해요. 우리 서버는 주문 검증과 상태 동기화만 해요.
- 판단 기준 3가지: ① 주문 흐름이 표준형인가 커스텀형인가 · ② 자체 주문 시스템이 이미 있는가 · ③ 부분 취소·환불·회계 처리에 자체 로직이 필요한가.
- 위임 범위를 초기에 잘못 정하면 6개월 뒤 "결제는 됐는데 주문이 안 잡히는" 정합성 사고가 반복돼요. 주문 데이터의 단일 소스가 우리 DB인지 PG인지 먼저 정해요.
이런 상황이라면
멤버십 서비스를 준비하는 PM예요. 결제는 붙이기로 했고 이제 "주문을 어디서 관리할지" 결정해야 해요. 지금까지는 "결제 성공 = 주문 완료"로 단순하게 생각했는데, 막상 설계에 들어가니 취소·환불·부분 취소·환불 정합성·회계 대사가 줄줄이 나와요. 개발자분이 물어요.
"주문 테이블을 우리 DB에 만들고 웹훅으로 동기화할까요? 아니면 커머스 API 쪽 주문을 그대로 쓸까요?"
두 선택지의 차이가 단순히 개발 공수만 달라지는 게 아니라, 운영에서 무엇을 책임지는지가 달라진다는 느낌이 들어요. 기준이 명확하지 않아요.
이 글은 주문 관리 범위를 어디까지 우리 서버가 가져가고 어디부터 커머스 API에 위임할지 판단하는 기준을 정리해요.
1"결제만 붙이기"와 "주문까지 위임하기"의 구조 차이
결제 API만 쓰는 경우 — 주문은 우리 서버가
결제 API(결제창·위젯)는 결제 승인에만 집중해요. 승인 이후 주문은 우리 서버가 직접 만들어요.
책임 범위:
- 주문 테이블 설계·생성
- 결제 성공 웹훅 수신 → 주문 상태 전이
- 결제 실패·중단 시 주문 롤백
- 취소·환불 요청 → PG 취소 API 호출 + 주문 상태 전이
- 부분 취소·부분 환불 시 금액 계산·정산 반영
- 회계 대사 (PG 리포트와 우리 DB 매일 비교)
장점은 자유도예요. 주문 스키마를 원하는 대로 짜고, 자체 주문 관리 로직을 만들 수 있어요.
커머스 API 쓰는 경우 — 주문 관리 위임
커머스 API는 결제 + 주문 생성 + 상태 관리를 한 번에 처리해요. 주문 ID가 PG 쪽에서 발급되고, 상태 전이도 PG가 관리해요.
책임 범위:
- 상품 카탈로그를 API/관리자에 등록
- checkout SDK로 주문서 호출
- 결제 성공 웹훅 수신 → 우리 DB에 주문 ID만 저장
- 취소·환불 요청 → 커머스 취소 API 호출 (상태 전이는 PG 쪽에서)
- 회계는 PG 리포트가 소스, 우리 DB는 캐시
장점은 단순성이에요. 주문 상태 기계·정합성을 직접 짜지 않아도 돼요. 단점은 PG 스키마에 맞춰야 하고, 커스텀 주문 흐름이 제약될 수 있어요.
2두 모델의 책임 분할 비교
| 책임 영역 | 결제 API (직접 관리) | 커머스 API (위임) |
|---|---|---|
| 주문 테이블 | 자체 DB | PG가 관리, 우리 DB는 참조만 |
| 주문 ID 발급 | 서버가 생성 | PG가 발급 |
| 결제 성공 → 주문 확정 | 웹훅 수신 로직 구현 | 자동 (checkout이 처리) |
| 결제 실패 → 주문 롤백 | 서버가 처리 | 자동 |
| 부분 취소 | 금액 계산 + 취소 API + DB 업데이트 | 취소 API 하나로 완료 |
| 환불 정합성 | 자체 로직 | PG가 처리 |
| 상태 전이 관리 | 자체 상태 기계 | PG 상태 기계 |
| 회계 대사 | PG 리포트 vs 우리 DB 매일 대조 | PG 리포트가 소스 |
| 커스터마이징 | 무제한 | PG 지원 범위 내 |
| 주문 조회 API | 자체 구현 | 커머스 API 호출 |
3판단 기준 3가지
① 주문 흐름이 표준형인가요, 커스텀형인가요
표준형: "장바구니 → 주문 → 결제 → 완료 → (취소·환불 가능)" 흐름이 일반 커머스와 동일해요. 커스텀형: 예약 대기 → 승인 → 결제 → 이행 확인, 또는 입찰 → 낙찰 → 결제처럼 일반 커머스와 다른 단계가 있어요.
표준형이면 커머스 API에 위임해도 대부분의 흐름이 맞아요. 커스텀형이면 결제 API + 자체 주문 관리가 더 유연해요.
② 자체 주문 시스템이 이미 있는가
이미 주문 DB와 상태 관리 로직이 있어요 → 결제 API를 써서 기존 시스템과 통합해요. 커머스 API로 넘기면 기존 시스템을 버리거나 이중 관리가 돼요. 새로 시작해요 → 커머스 API가 유리해요. 주문 로직을 처음부터 짜는 대신 검증된 API를 써요.
③ 부분 취소·환불·회계에 자체 로직이 필요한가요
필요하예요:
- 쿠폰·적립금·할인이 복잡해서 취소 시 부분 반환 계산이 자체적이어야 해요
- 회계 시스템과 직접 연동해야 한다 (ERP, 자체 정산 엔진)
- 부분 취소 시 재고 반환 로직이 우리 서비스 고유해요
필요하지 않아요: 표준 부분 취소·환불 로직으로 충분해요.
필요하면 결제 API + 자체 주문. 아니면 커머스 API.
4시나리오별 권장 모델
일반 쇼핑몰 (B2C)
커머스 API. 주문 흐름이 표준형이고, 부분 취소·환불 로직도 일반적이에요. 주문 관리를 처음부터 짜는 비용이 커요.
SaaS 구독 (단일 플랜)
결제 API + 자체 간단한 주문 테이블. 주문 자체가 단순하므로 커머스 API까지 쓸 필요가 없어요. 구독 관리가 메인이라면 커머스 구독 API를 쓰고 주문은 그 안에 포함.
커스텀 주문 흐름 (예약·경매·수주)
결제 API + 자체 주문 관리. 일반 커머스와 상태 전이가 다르므로 커머스 API에 끼워 맞추기 어려워요.
B2B 마켓플레이스
커머스 + 마켓플레이스 그룹 API. 그룹별 가격·한도·정산이 필요하면 커머스 + 마켓플레이스를 같이 써요. 자체 구축하면 개발 공수가 훨씬 커요.
기존 쇼핑몰에 결제만 추가
결제 API. 이미 주문 시스템이 있다면 결제만 붙여요. 커머스 API로 이관은 별도 프로젝트.
1인 판매자·상담 기반
결제링크. 주문 관리조차 불필요해요. 링크를 보내고 결과를 관리자에서 확인해요.
5혼합 모델 — 처음부터 완벽히 나누지 않아도 돼요
많은 서비스가 결제 API + 자체 주문 관리로 시작해 커머스 API로 이관하거나, 반대로 커머스 API + 일부 특수 주문만 결제 API 직접으로 혼합해요.
초기 판단에서 중요한 건 "주문의 단일 소스(source of truth)가 어디인가"를 명확히 하는 거예요.
- 단일 소스가 우리 DB: 결제 API. 웹훅은 보조 정보.
- 단일 소스가 PG/커머스 API: 커머스 API. 우리 DB는 캐시.
두 쪽 모두 단일 소스로 잡으면 정합성 사고가 터져요. "우리 DB에는 주문 완료인데 PG에는 취소 상태" 같은 불일치가 자주 발생해요.
6잘못된 선택에서 오는 사고 패턴
"결제 API인데 주문 관리가 약함"
결제 API를 쓰면서 주문 관리 로직을 나중에 붙이는 경우. 웹훅 재전송 처리, 중복 결제 방지, 부분 취소 금액 계산이 누락되면 결제는 됐는데 주문이 안 잡히는 사고가 자주 발생해요. 월 거래 건수가 늘수록 누적돼요.
"커머스 API인데 자체 주문 DB와 중복 관리"
커머스 API를 쓰면서도 "혹시 모르니" 자체 주문 DB를 만드는 경우. 두 쪽 상태가 어긋날 때 어느 쪽을 믿을지 기준이 없어 운영이 혼란해져요. 커머스 API를 쓰기로 했으면 우리 DB는 주문 ID + 최소 캐시만 저장해요.
"커스텀 주문 흐름에 커머스 API 억지 매핑"
예약 승인 → 결제 → 체크인 확인 → 정산 같은 커스텀 흐름을 커머스 API의 표준 상태에 끼워 맞추는 경우. 상태 매핑 로직이 누적되면서 유지보수 비용이 급증해요.
다음 단계
주문 관리 범위를 정했다면 다음은 상품·회원·체크아웃 설계예요.
추천 콘텐츠
결제 API만 붙였는데 3개월 뒤 커머스 API로 갈아탄 팀의 기준 결제 vs 커머스 전환 판단의 상세 기준.
상품 관리 — 직접 짤까, 맡길까? 카탈로그를 자체 DB로 짤지 커머스 API에 둘지.
체크아웃 플로우 설계 장바구니 → 주문 → 결제 흐름 분기점.