결제 webhook 정산·환불·보안 통합 완료
목차
지난번부터 남겨둔 결제 플랫폼 webhook 처리 기능들을 마무리했다. 정산 후처리, 환불 시 역분개, IP 토글을 통한 접근 제어까지—세 가지 핵심 기능이 모두 구현되면서 webhook 통합이 한 단계 완성된 느낌이다.
처음 맞닥뜨린 복잡성
webhook을 처음 설계할 때는 "결제 성공 이벤트 받으면 주문 상태 업데이트하고 끝" 정도로 생각했다. 하지만 실제로는 훨씬 복잡했다. 결제가 완료되면:
- 정산 후처리: 실제 지급이 언제 일어나는지, 정산 수수료는 어떻게 차감하는지, 지갑에 최종 금액은 언제 반영되는지
- 환불 흐름: 결제를 취소해야 하면 단순히 상태만 바꾸는 게 아니라, 이미 처리된 거래를 회계상 원복(역분개)해야 함
- 보안: 위조된 webhook 요청을 막기 위해 발신 IP를 화이트리스트로 관리해야 함
초기에는 이런 것들을 "일단 기본 기능부터 하고 나중에" 하는 식으로 TODO로 남겨뒀는데, 본격적으로 운영에 들어가면서 이들이 얼마나 중요한지 깨닫게 됐다.
세 가지 기능의 의미
정산 후처리와 지갑 통합
결제 플랫폼에서 입금 확인이 오면, 그 시점에 사용자 지갑에 금액을 반영해야 한다. 근데 단순 덧셈이 아니다. 수수료가 있으면 빼고, 특정 고객한테는 보조금이 적용되고, 정산 대기 기간이 있으면 그 기간 동안은 보류 상태여야 한다. payment/web 쪽에서 이런 후처리 로직을 다루고, 그 결과를 wallet/web으로 전달하면서 두 도메인이 손을 잡게 된다.
환불의 역분개
환불 요청이 들어오면 기존 거래를 "취소"하는 게 아니라, 정확히는 음수 거래를 기록하는 방식으로 처리한다. 예를 들어:
원래: +10,000원 (결제 완료)
취소: -10,000원 (환불)
결과: 0원 (장부상 맞음)
이렇게 하면 감사(audit) 추적도 명확하고, 실수로 같은 거래를 두 번 환불하는 사고도 방지할 수 있다. 단순히 상태 플래그를 "REFUNDED"로 바꾸는 것보다 훨씬 견고하다.
IP 화이트리스트를 통한 접근 제어
webhook은 외부 서비스로부터의 요청인데, 위조된 요청이 들어오면 시스템이 엉망이 된다. IP 토글 기능을 추가하면서:
- 결제 플랫폼의 서버 IP만 화이트리스트
- 데이터센터 이전이나 IP 변경 시 유연하게 대응 가능
- 응급 상황에서 특정 IP를 빠르게 차단할 수 있음
운영 관점에서 생각해보니 이게 정말 필요한 방어막이었다.
작업 진행 중 고민했던 점
이 세 기능은 서로 연관이 있으면서도 독립적인 부분들이다:
- 정산 후처리는 정상 흐름(happy path)
- 환불은 비정상 시나리오(sad path)
- IP 토글은 보안 레이어
각각을 순차적으로 하나씩 구현할 수도 있었지만, 한 번에 마무리하기로 결정했다. 이유는:
1. 세 기능이 모두 같은 webhook 처리기 내에서 필요
2. 하나씩 배포하면 배포 사이사이에 불완전한 상태가 오래 유지됨
3. 테스트 케이스도 함께 작성하면서 시너지
팀과 공유할 때 중요한 부분
이런 결제 시스템 변경은 혼자만 알면 위험하다. 다른 팀원들도:
- 정산이 실시간이 아니라 배치로 일어날 수 있다는 점
- 환불 요청이 들어왔을 때 단순히 상태만 바꾸면 안 된다는 점
- webhook이 정지되면 정산이 멈춘다는 점
을 알아야 한다. 코드 리뷰할 때도 이런 도메인 지식을 자연스럽게 녹여내야 하고, 나중에 누군가 이 코드를 유지보수할 때를 대비해서 충분한 주석과 로그를 남겨뒀다.
결제 시스템은 신뢰성이 생명인 영역이라, 작은 기능이라도 "이걸 놓치면 어떤 사고가 날까"를 먼저 생각하는 습관이 중요하다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.