결제 플랫폼 월별 정산 누적액 추적 오류 해결

결제 플랫폼의 출금 로직에서 월 단위 누적액(carryover) 처리를 개선했다.

출금 정산과 누적액의 관계

결제 플랫폼을 운영하면서 가장 까다로운 부분 중 하나가 정산 주기와 미정산 잔액 관리다. 보통 플랫폼은 일일, 주간, 월간 단위로 정산을 진행하는데, 각 주기마다 정산 기준 미달(예: 최소 정산액 1만 원 미만)로 인해 다음 주기로 미루어지는 금액들이 쌓인다. 이게 바로 'carryover'인데, 이 누적액을 어떻게 다루느냐에 따라 가맹점주의 현금흐름과 정산 정확도가 크게 달라진다.

내가 마주친 상황은 월 단위 정산 시 이전 주기의 미정산액을 다음 달로 넘기는 로직이 명확하지 않아서, 실제로는 정산되어야 할 금액이 어디론가 사라지거나 중복 계산되는 엣지 케이스가 발생하고 있었다는 것. 특히 한 달 중반에 출금 요청을 여러 번 하는 가맹점의 경우, 누적액이 정확하게 추적되지 않으면서 "어제는 1,500원이 대기 중이었는데 오늘은 사라졌네?" 같은 민원이 들어오곤 했다.

월별 누적액 흐름 정리

이번 작업은 매달 정산 시점에 이전 달의 carryover를 명시적으로 계산하고, 그것을 현재 달 정산에 포함시키는 로직을 정립한 것이다.

핵심은 월마다 명시적인 경계를 그어서, "이전 달 미정산액 + 이번 달 수익 = 이번 달 정산액"이라는 공식을 보장하는 것이다.

정산 누적액의 일반적 패턴

이런 문제는 결제 플랫폼뿐 아니라 정기 배송, 수수료 정산, 포인트 시스템 등 어디서든 반복되는 패턴이다. 특히:

• 최소 정산액 정책: 너무 빈번한 출금 요청을 막기 위해 일정액 이상일 때만 정산하도록 설정
• 정산 주기 미스매치: 사용자는 매일 확인하고 싶지만, 플랫폼은 주 1회나 월 1회만 출금을 처리하는 경우
• 세금/수수료 공제 시점: carryover에서 수수료를 빼야 하나, 아니면 정산 시점에 빼나?

이 모든 케이스를 한 곳에서 관리하면 로직이 복잡해진다. 그래서 정산 관련 데이터를 다룰 때는 상태 다이어그램을 먼저 그려보는 게 좋다. "미정산 → 기다림 → 누적 → 정산 완료 → 초기화"처럼 명확한 상태 전이를 설계하면, 나중에 버그를 찾을 때 어느 단계에서 꼬였는지 빨리 파악할 수 있다.

테스트와 모니터링

이런 금전 관련 로직은 '거의 맞음'이 통하지 않는 영역이다. 1원이라도 차이나면 감사 대상이 될 수 있고, 사용자 신뢰가 떨어진다. 그래서 나는 이 변경 후 다음을 체크했다:

• 월말 정산 시나리오 몇 가지를 손으로 계산해서 DB 결과와 비교
• carryover가 정말 0으로 리셋되는지 매달 확인
• 연속 몇 달간 누적액 변화를 그래프로 시각화

정산 로직이 한번 잘못 배포되면 수십만 명의 지갑에 영향을 주니까, 배포 전 review와 배포 후 모니터링이 필수다.