거래 상태 모델

거래 상태는 자금 이동이 어디까지 진행됐는지 나타냅니다. 고객 지갑에서는 입금 대기·출금 처리 중·완료를 표시하고, 계정 간 이체나 결제에서는 자금 이동 결과에 따라 업무를 진행합니다. API 호출 성공, 거래 생성, 자금 이동 완료는 서로 다른 판단입니다.

HTTP 응답과 거래 결과 구분

확인한 내용	알 수 있는 것	추가로 확인할 것
HTTP 성공과 success: true	해당 API 요청이 성공적으로 처리됨	반환된 거래의 상태
deposit_id 또는 withdrawal_id	조회·추적할 거래가 존재함	완료 조건 충족 여부
비최종 거래 상태	처리가 아직 진행 중임	같은 거래의 이후 상세 상태
거래별 성공 조건	자금 이동 성공을 업무에 반영할 수 있음	관련 금액과 원장 정합성

예를 들어 출금 생성이 성공해 withdrawal_id를 받았어도 출금은 아직 처리 중일 수 있습니다. 입금 상세 조회가 성공해도 그 입금의 status가 COMPLETED가 아니라면 충전 성공으로 표시하지 않습니다.

입금과 출금의 상태 필드

리소스	상태 필드	해석
외부 입금	status	컨펌·승인·환불 등을 포함한 상세 상태
내부 입금	status	PENDING 또는 COMPLETED 표시
외부 출금·내부이체	status, user_status	상세 처리 상태와 고객 표시용 상태

출금의 status와 user_status는 값의 범위가 다릅니다. status에는 REQUESTED, HOT_STAGE, HOT_FAILED 등이 있고 user_status에는 PENDING, PROCESSING, FAILED 등이 있습니다. 두 필드를 같은 enum으로 비교하거나 입금 응답에 user_status가 있다고 가정하지 않습니다.

고객 지갑의 출금 상태 처리

user_status	의미	고객 화면·업무 처리
PENDING	요청 접수와 처리 대기	출금 대기 표시, 상세 조회 유지
PROCESSING	처리 진행	처리 중 표시, 중복 출금 방지
COMPLETED	완료	성공 조건과 거래 정보를 확인한 뒤 완료 표시
FAILED	처리 실패	실패 결과와 잔액 복구 확인
REJECTED	거절	사유 확인과 업무 종료
CANCELLED	취소	취소 결과와 잔액 확인

외부 출금은 status: COMPLETED, user_status: COMPLETED, 유효한 tx_hash를 함께 확인합니다. tx_hash가 있어도 처리 중이면 출금 완료가 아닙니다. 내부이체는 request_type: INTERNAL과 두 완료 상태를 확인하며 온체인 hash를 요구하지 않습니다.

출금이 오래 처리 중인 경우 기존 요청 ID와 거래 ID를 유지해 계속 추적합니다. 처리 지연을 새 출금을 만들 근거로 사용하지 않습니다. 자세한 흐름은 출금 처리 흐름을 참고합니다.

입금 상태 처리

외부 입금의 진행 상태에는 PENDING, INSPECTED, APPROVE_PENDING, APPROVED, VERIFIED가 있습니다. 입금 성공은 COMPLETED일 때만 반영합니다.

REFUND_REQUIRED, REFUND_REQUESTED, REFUND_PENDING은 환불 대상 또는 환불 진행 상태입니다. REFUNDED와 FAILED는 입금 성공이 아닌 종료 결과입니다. 고객 화면에서는 처리 중·환불 진행·실패를 구분해 표시할 수 있으며, 원본 상태값도 저장합니다.

상태 코드는 전체 값을, 입금 처리 흐름은 지갑의 적립 판단과 조회 방법을 설명합니다.

신규 거래 발견과 이후 상태 변경

Cursor 목록 조회는 새 거래를 찾는 방법이고 상세 조회는 이미 찾은 거래의 상태를 갱신하는 방법입니다.

첫 목록 조회: 입금 200 발견, status=PENDING, cursor=200 저장
  → 이후 목록 조회는 200 이후의 신규 입금을 발견
  → 별도 상세 조회로 입금 200의 COMPLETED 확인

이 예시에서 입금 200이 완료되어도 같은 ID가 cursor 목록에 다시 나타나지는 않습니다. 신규 발견과 비최종 거래 상세 조회를 따로 운영해야 지갑의 완료 내역을 놓치지 않습니다. 동일한 원칙은 출금에도 적용됩니다.

최종 상태가 된 거래는 정상 상태 추적 대상에서 제외하고 최종 결과를 저장합니다. 원장은 확정 변동을 추가하는 기록이므로 cursor로 신규 항목을 수집합니다. 조회 결과의 순서와 거래 완료 시점을 같은 것으로 해석하지 않습니다.

업무에 반영하는 시점

업무	반영 기준
고객 지갑 충전 완료	외부 입금 status: COMPLETED
고객 외부 출금 완료	외부 출금의 두 완료 상태와 유효한 tx_hash
계정 간 이체 완료	내부이체 유형과 두 완료 상태
주문 결제 완료	주문에 연결된 내부이체의 완료 조건
가맹점 외부 정산 완료	정산에 연결된 외부 출금의 완료 조건

완료 확인 후의 고객 알림이나 주문 상태 변경은 같은 응답을 다시 처리해도 한 번만 반영되도록 합니다. 잔액 변화는 보조 검증이며 개별 거래 상태를 대신하지 않습니다.

저장과 재시작 복구

거래 유형·ID, 고객사 업무 ID, 원본 status, 출금의 user_status, 마지막 확인 시각, 다음 확인 시각, 최종 여부를 저장합니다. 재시작 후에는 저장된 비최종 거래의 조회를 이어갑니다.

상태의 문자열 순서나 코드 크기로 처리 진척도를 비교하지 않습니다. 저장된 최종 결과와 이후 응답이 모순되거나 알 수 없는 상태가 반환되면 원본 정보를 보존하고 자동 업무 반영을 멈춰 확인합니다. HTTP 오류의 재시도는 오류 처리와 재시도, cursor와 상태 추적의 구성은 증분 데이터 동기화를 참고합니다.