결제 상태 매핑: 7가지 상태값과 완료 확정 원칙

핵심 요약

결제 상태를 '성공/실패' 두 개로만 정의하면 운영 단계에서 반드시 문제가 생겨요. 가상계좌 입금 대기, 부분 취소, 만료까지 최소 7가지를 잡아야 해요.
결제 완료는 결제창이 닫히는 순간이 아니라, 서버가 승인 결과를 확인하고 주문 상태를 확정하는 순간이에요. 기획서에 완료 기준을 이 문장으로 적어야 재고·권한·알림이 어긋나지 않아요.
개발자와는 최소 4가지를 합의해야 한다: 주문 선생성, 승인 후 상태 업데이트, 웹훅 백업, 중복 처리.

1결제 상태는 실제로 몇 가지일까요

통합결제 서비스가 내부적으로 관리하는 상태는 '성공/실패'보다 훨씬 세분화되어 있어요. 아래 7가지를 기본으로 알고 있어야 해요.

상태값	의미	발생 시점	고객 대응 메시지
결제 요청 (Ready)	결제창이 호출된 상태	고객이 '결제하기' 클릭 시	결제창 진행 중
결제 대기 (Waiting)	입금을 기다리는 상태	가상계좌 발급 직후	"입금 기한 내에 입금해주세요"
결제 완료 (Success)	전산상 결제가 확정된 상태	카드사/은행 승인 직후	"결제가 완료됐어요"
결제 실패 (Failed)	결제가 중단되거나 거절된 상태	잔액 부족, 한도 초과, 창 닫기	"결제 실패: [사유] 재시도하시겠습니까?"
결제 취소 (Cancelled)	결제 전체가 무효화된 상태	관리자 페이지에서 전체 취소	"결제 취소가 완료됐어요"
부분 취소 (Partially)	결제 금액 중 일부만 취소된 상태	주문 상품 중 일부만 취소	"일부 상품의 취소가 완료됐어요"
결제 만료 (Expired)	결제 가능 시간이 지난 상태	가상계좌 입금 기한 초과 등	"입금 기한이 만료되어 주문이 취소되었습니예요"

2상태 흐름: 결제 요청부터 최종 확정까지

결제 상태는 고정된 값이 아니라 화살표를 타고 흐르는 동적인 데이터예요. 이 흐름을 기획자가 먼저 잡지 않으면 개발자는 예외 케이스를 처리하지 못해 에러를 내요.

웹훅 status 코드 매핑

웹훅 status	의미	비즈니스 상태
`status: 1`	결제 완료	Success
`status: 2`	가상계좌 발급	Waiting
`status: 20`	결제 취소	Cancelled

승인 이후 금액이 돌아가는 경로는 두 가져요. PG 전산에서 되돌리는 취소와, 가맹점이 고객 계좌로 직접 송금하는 환불이에요. 결제 수단별 기준은 취소와 환불, 뭐가 다른가요?에서 정리했어요.

3결제 완료는 어디서 확정하는가

사용자는 결제창이 닫히면 완료라고 생각해요. 하지만 서비스 입장에서는 그다음 단계가 더 중요해요.

단계	사용자에게 보이는 것	서비스 안에서 실제로 일어나는 것
1. 주문 시작	주문서 작성	주문 생성 (`pending`)
2. 결제 진행	결제창/인증 화면	PG 결제 요청
3. 승인 직후	결제 성공처럼 보임	승인 결과 수신 대기
4. 서버 확정	주문 완료 화면	주문 상태 `done` / `confirmed` 업데이트
5. 후속 처리	상품/권한/알림 수신	재고 차감, 권한 부여, 정산 기준 반영

3단계와 4단계를 같은 것으로 보면 안 된다는 점이 핵심이에요.

완료 기준 후보와 판단

완료 기준 후보	보통 쓰는가	판단
결제창이 닫힌 시점	거의 안 씀	너무 이르예요
브라우저가 성공 응답을 받은 시점	위험함	서버 반영 누락 가능
서버가 승인 확인 후 주문 상태를 바꾼 시점	가장 일반적	권장

기획 문서에는 이 문장이 적혀 있어야 해요.

결제 완료는 서버가 승인 결과를 확인하고 기존 주문 상태를 확정한 시점으로 봐요.

이 기준이 있어야 완료 화면 노출, 재고 확정, 권한 부여, 알림 발송 시점이 모두 맞춰져요.

왜 주문을 먼저 만들고 나중에 상태를 바꿀까요

결제 전에 어떤 상품을 사는지 이미 정해야 해요
재고, 쿠폰, 할인, 배송지 같은 정보가 먼저 묶여야 해요
결제 성공 후에는 새 주문을 만드는 것보다 기존 주문 상태를 업데이트하는 편이 안전해요

그래서 보통 흐름은: 주문 생성 → pending → 결제 승인 → 서버 확인 → done / confirmed.

4개발자와 반드시 합의해야 하는 4가지

1) 주문은 언제 생성할까요

결제 전에 주문을 먼저 만들지 / 어떤 상태값으로 시작할지 / 실패 시 어떻게 남길지

2) 승인 후 어떤 상태로 바꾸나

done, confirmed, completed 중 어떤 상태를 쓸지 / 완료 화면은 언제 보여줄지 / 고객 알림은 언제 보낼지

3) 웹훅은 어떻게 쓸까

브라우저가 끊겨도 PG가 서버로 결과를 보내줄 수 있으니 웹훅은 백업 경로처럼 봐요.

웹훅이 오면 누락된 주문 상태를 복구할지 / 이미 반영된 주문이면 중복 업데이트를 막을지 / 고객에게 다시 알림을 보낼지

4) 실패·중복은 어떻게 막나

같은 주문으로 두 번 결제되면 어떻게 막을지 / 실패 시 재고·쿠폰·권한을 복구할지 / 결제 결과 확인 중 상태를 둘지

5기획서에 이렇게 쓰면 개발자가 바로 구현해요

Before: 추상적인 기획

결제 성공 시: 주문 완료 화면을 보여줘요.
결제 실패 시: 이전 화면으로 돌아가요.
취소 시: 돈을 돌려줘요.

After: 실전형 상태 정의 테이블

전후 상태 변화	전환 조건 (Trigger)	화면 및 알림 대응	기획자 확인	개발자 구현
Ready → Success	결제 승인 응답 수신	'주문 완료' 페이지 이동, 알림톡 발송	완료 화면 문구, 알림 메시지	서버 승인 확인 후 DB 상태 변경
Ready → Waiting	가상계좌 발급 성공	계좌 정보 안내 페이지 노출	입금 기한 정책 (24h/48h)	가상계좌 웹훅 수신 처리
Success → Cancelled	관리자 전체 취소 실행	취소 완료 알림 발송	취소 사유별 고객 안내 문구	재고 복구 로직 연동
Success → Partially	주문 상품 중 1개 취소	잔여 금액 안내, 부분 취소 알림	부분 취소 허용 범위 정책	배송비 재계산 로직
Waiting → Expired	입금 기한(24h) 초과	"주문 자동 취소" 알림	만료 안내 알림 시점	만료 웹훅 수신 후 DB 동기화

6상태별 고객 화면 대응 샘플

결제 대기 (가상계좌)

핵심 요소: 입금할 은행, 계좌번호, 예금주명, 입금 기한(시/분까지), 입금 금액.
문구 예시: "내일 오후 2시까지 입금되지 않으면 주문이 자동으로 취소돼요."

결제 실패

핵심 요소: 실패 사유(한도 초과, 잔액 부족 등), 다른 결제수단 선택 버튼, 고객센터 연결.
문구 예시: "카드 한도가 초과됐어요. 다른 카드를 사용하거나 간편결제를 이용해보세요."

부분취소 완료

핵심 요소: 취소된 상품명, 취소 금액, 최종 결제 유지 금액, 취소 완료 예정일.
문구 예시: "3개 상품 중 1개 상품(15,000원)의 취소가 완료됐어요. 남은 결제 금액은 30,000원예요."

7삽질 포인트: 자주 빠지는 3가지

결제 요청 중 '유령 주문' 처리

고객이 결제창을 띄워놓고 창을 닫아버리면 DB에 '결제 요청' 상태의 데이터가 계속 쌓여요. 일정 시간(예: 30분)이 지나도 승인이 나지 않는 요청은 자동으로 '실패' 또는 '만료' 처리하는 배치 로직을 기획에 포함해야 해요.

부분취소 후의 '최종 상태' 정의

10만 원 결제 건에서 3만 원을 부분 취소하면, 이 주문 상태는 '결제 완료'인가 '부분 취소'인가? 보통 status 필드는 PARTIAL_CANCEL로 바꾸고 paid_amount 필드에서 남은 금액을 관리하는 방식을 추천해요.

가상계좌 입금 기한과 주문 만료의 동기화

PG사 전산의 가상계좌 만료 시간과 서비스 DB의 주문 만료 시간이 1초라도 어긋나면 안 돼요. 가상계좌 만료 시점에 결제 솔루션으로부터 '만료 웹훅'을 받아 DB 상태를 변경하는 프로세스를 반드시 설계에 넣어야 해요.

최종 체크리스트

주문을 먼저 만들고 어떤 상태로 시작하는지 정했어요
결제 완료를 서버 승인 후 주문 상태 확정 시점으로 정의했어요
재고 차감, 권한 부여, 알림 발송 시점을 정했어요
실패 시 주문 상태, 재시도, 복구 기준을 정했어요
브라우저 이탈 시 웹훅을 백업 경로로 쓸지 정했어요
중복 결제·중복 확정을 막는 기준이 있어요

다음 단계

바로 참고할 문서

개발 문서: 결제 상태별 API 가이드
도입 문의: 통합결제 솔루션 상담