Jangkyu Lee
가상계좌 입금 확인, 발급 성공을 결제 완료로 착각했다면
가상계좌 발급 API가 성공했습니다.
개발자는 안심했고, 대표는 매출을 기대했고, 고객은 아직 은행 앱을 열지 않았습니다.
세 사람 중 돈을 보낸 사람은 없습니다.
가상계좌는 거래를 구분해 입금을 받는 데 쓰는 계좌입니다. 그런데 계좌 번호를 발급한 일과, 고객이 입금한 일과, 그 돈을 우리 청구 건에 반영한 일은 각각 다릅니다.
청구·수금 자동화 서비스 청구스를 만드는 이장규입니다. B2B 결제를 설계할 때 자주 한 덩어리로 보게 되는 ‘결제 성공’을 조금 나눠보고 싶습니다.
가상계좌 발급 성공은 무엇이 성공한 걸까요?
토스페이먼츠의 주문형 가상계좌 연동을 예로 들겠습니다. 결제 승인 API를 호출해 계좌가 발급돼도 상태는 WAITING_FOR_DEPOSIT, 즉 입금 대기입니다. 구매자가 입금하면 DONE으로 바뀝니다. 공식 연동 안내
여기서 제품 화면의 문구가 중요해집니다.
발급 직후 초록색으로 “결제 완료!”를 띄우면 고객은 끝났다고 생각할 수 있습니다. 하지만 그 시점에 필요한 안내는 입금할 은행·계좌·금액·기한입니다.
공급자 화면도 마찬가지입니다. ‘발급 성공 20건’과 ‘입금 확인 20건’은 전혀 다른 현황입니다. 같은 성공 배지 아래 합치면 돈을 기다리는 업무가 화면에서 사라집니다.
입금 확인과 청구 잔액 반영도 구분해야 합니다
다음은 특정 서비스의 구현 명세가 아닌, 제품을 검토하기 위한 개념적인 흐름입니다.
계좌 발급 → 입금 대기 → 입금 확인 → 해당 청구 건 수납 반영
주문 한 건에 정확한 금액을 한 번 입금하는 방식이라면 연결이 비교적 단순합니다. 반면 거래처별 고정 계좌로 여러 청구 건의 돈을 받는 업무라면, 어느 청구에 얼마를 반영할지까지 정해야 합니다.
예를 들어 330만 원짜리 청구가 두 건 있는데 500만 원이 들어왔다고 합시다. 들어온 돈은 500만 원이고, 전체 청구 잔액은 160만 원입니다. 그래도 각 청구 건에 얼마를 배정할지는 별도 규칙이 필요합니다.
이 계산은 가상의 예시입니다. 모든 가상계좌가 이런 합산·부분 입금을 허용한다는 뜻도 아닙니다. 토스페이먼츠의 일반 주문형 가상계좌 정책은 정해진 금액을 기한 내 한 번에 보내는 방식입니다. 상품·계약마다 수납 조건을 먼저 확인해야 합니다. 결제수단 정책
‘가상계좌 지원’이라는 체크박스 하나로는 우리 업무에 맞는지 알기 어렵습니다. 주문별인지 거래처별인지, 금액이 다르면 어떻게 되는지, 청구가 여러 건이면 어디에 반영되는지까지 봐야 합니다.
웹훅을 두 번 받으면 감사 메시지도 두 번 갈까요?
웹훅은 결제 상태가 바뀌었을 때 우리 서버가 알림을 받는 방식입니다. 상태를 반영하는 출발점이지, 알림을 받은 횟수만큼 입금을 더하는 장치는 아닙니다.
토스페이먼츠는 PAYMENT_STATUS_CHANGED와 DEPOSIT_CALLBACK을 함께 등록하면 가상계좌 상태 변경 때 웹훅이 두 번 전송될 수 있다고 안내합니다. 웹훅 이벤트 문서
그래서 검토할 질문도 “웹훅 붙였나요?” 다음으로 넘어가야 합니다.
같은 거래의 알림을 다시 받아도 수납 금액이 한 번만 반영되는가?
최신 결제 상태를 확인하고, 취소나 정정도 처리하는가?
입금이 반영된 뒤에는 미입금 안내가 멈추는가?
반영에 실패한 건을 운영자가 찾아서 이어 처리할 수 있는가?
결제 담당자에게 중요한 것은 서버가 알림을 잘 받았다는 사실 다음에 있습니다. 이미 낸 고객에게 다시 돈을 달라고 하지 않는 것까지 이어져야 하니까요.
제품 데모에서 이 세 장면을 같이 보면 좋겠습니다
첫째, 계좌만 발급하고 아직 입금하지 않은 상태.
둘째, 입금은 확인됐지만 확인·반영 작업이 남은 상태.
셋째, 수납이 반영돼 잔액과 다음 안내가 달라진 상태.
세 장면이 구분되면 기능 목록보다 많은 것을 알 수 있습니다. 사람이 어디서 판단해야 하는지, 화면의 어떤 숫자를 믿고 고객에게 연락할 수 있는지가 보입니다.
청구스는 청구서 발송과 입금 대조, 수납 상태와 연체 안내를 연결하는 일을 하고 있습니다. 정확한 조건의 일반 계좌 입금은 설정에 따라 자동 수납하며, AI가 추천한 입금 후보는 사람이 확인합니다. 가상계좌의 수납 규칙은 일반 계좌의 이름 매칭과 구분합니다.
결제 기능을 만드시는 분들은 어느 순간을 ‘완료’라고 표시하시나요?
계좌 번호가 생긴 순간인지, 돈이 들어온 순간인지, 운영팀이 다음 할 일을 정확히 알게 된 순간인지 궁금합니다.