가상계좌 입금 처리

핵심 요약

• 가상계좌는 결제창에서 바로 돈이 빠지는 방식이 아니에요. 먼저 계좌를 발급받고, 구매자가 나중에 직접 입금해요.
• 중요한 건 입금 시점을 알 수 없다는 점​​이에요. 바로 보낼 수도 있고, 저녁이나 다음 날 보낼 수도 있어요.
• 그래서 issued가 왔다고 결제 완료로 처리하면 안 돼요. 이때의 올바른 상태는 입금 대기​​예요.

1issued는 결제 완료가 아니라 계좌 발급이에요

가상계좌에서 결제창이 끝나면 고객이 받는 것은 결제 완료 메시지​​가 아니라 입금할 계좌번호​​예요. 돈이 들어온 상태가 아니라, 돈을 보낼 준비가 끝난 상태에 가까워요.

고객은 그 계좌로 바로 입금할 수도 있고, 몇 시간 뒤에 보낼 수도 있고, 다음 날 보낼 수도 있어요. 그래서 issued가 왔다고 해서 결제가 끝난 것은 아니에요.

이 시점에 해야 할 일은 결제 완료 처리가 아니라 입금 안내​​예요. 고객에게 아래 정보를 명확하게 보여줘야 해요.

• 은행명
• 계좌번호
• 예금주
• 입금 기한
• "입금 확인 후 주문이 최종 확정돼요" 안내 문구

문구도 처음부터 다르게 써야 해요.

• "결제가 완료됐어요" → X
• "가상계좌가 발급되었습니예요" → O
• "입금 확인 후 주문이 최종 확정돼요" → O

2주문 상태는 issued와 done을 분리해서 관리해야 해요

가상계좌에서 가장 흔한 실수는 issued와 done을 같은 상태처럼 다루는 거예요. 하지만 둘은 완전히 달라요.

후속 액션도 다르게 가져가야 해요.

• issued: 계좌 안내, 입금 기한 안내
• done: 주문 확정, 재고 차감, 배송/서비스 시작
• expired: 자동 취소, 재고 반환, 재주문 유도

가상계좌를 카드결제처럼 한 번에 처리하면, 미입금 주문까지 결제 완료로 보이게 되고 운영이 쉽게 꼬여요.

3실무에서는 프론트와 서버 역할을 나눠서 처리해요

2번이 상태 정의라면, 3번은 누가 무엇을 처리하느냐​​의 문제예요.

• 프론트​: issued를 받으면 입금 안내 화면을 보여줘요.
• 서버​: 주문 상태를 issued로 저장하고, 이후 입금 완료를 확인하면 done으로 바꿔요.

즉, 프론트는 계좌 정보를 안내하고, 서버는 최종 상태를 확정해요. 실무 흐름은 아래처럼 이어져요.

1. 결제창에서 issued 수신
2. 프론트에서 계좌번호·은행명·입금 기한 안내
3. 서버에서 주문 상태를 issued로 저장
4. PG사 입금 완료 통지 → 부트페이 → 가맹점 서버 순서로 웹훅 수신
5. 서버에서 주문 상태를 done으로 변경

가상계좌는 브라우저 화면만 보고 끝내면 안 되고, 웹훅 수신이 실제 완료 처리의 기준​​이에요. 그리고 가상계좌 웹훅은 한 번이 아니라 두 번 온다는 점을 같이 설계해야 해요.

• status: 2 → 가상계좌 발급 (issued, 입금 대기)
• status: 1 → 실제 입금 완료 (done, 주문 확정)

즉, status: 2가 왔을 때는 계좌 안내만 하고, status: 1이 왔을 때만 실제 완료 처리로 넘겨야 해요.

웹훅은 두 단계 설정이 모두 있어야 작동해요

가상계좌 웹훅이 가맹점 서버까지 도달하려면 부트페이와 PG사 양쪽 모두 설정이 필요해요. 둘 중 하나라도 비면 실제 입금이 들어와도 완료 웹훅이 오지 않아요.

• 1차 설정 (부트페이): 관리자 개발자 설정 > 웹훅 설정에 HTTPS 엔드포인트​​를 등록해요.
• 2차 설정 (PG사): 사용하는 PG사 관리자/전산에 가상계좌 입금통보 URL​​을 등록해요. 이 URL은 부트페이가 PG 통지를 받는 엔드포인트이고, 여기서 수신된 입금 이벤트가 가맹점 웹훅으로 전달돼요.

PG사별로 관리자 메뉴 이름과 등록할 URL이 달라요. 아래 표에 자주 쓰는 PG사 기준으로 정리해요. 모든 URL은 HTTPS, 부트페이 게이트웨이(gw.bootpay.co.kr)로 통일돼 있어요.

PG별 관리자 실제 화면은 아래와 같아요.

KCP - 상점정보관리 > 정보변경 > 공통 URL(결제결과)정보

나이스페이먼츠 - 결제데이터통보의 가상계좌 행 URL/IP

KG이니시스 - 상점정보 > 결제수단 정보 > 가상계좌 입금통보URL(IP)

웰컴페이먼츠 - 상점 정보 > 결제수단정보 > 가상계좌 입금통보URL(IP)

키움페이 - 고객지원 > 기술지원 > 연동정보설정 (발행 통지URL / 결과 통지URL 이중 등록)

몇 가지 자주 놓치는 포인트가 있어요.

• KCP는 SSL을 TLS 1.2 이상​​으로 설정해야 해요. 구버전 TLS를 쓰면 통지 연결 자체가 실패해요.
• 서버 아이피 필터를 쓴다면 부트페이 Outbound IP 223.130.82.4, 223.130.82.130, 223.130.82.131을 화이트리스트에 넣어요.
• 키움페이는 통지 URL이 두 개​​예요. 발행 시점과 입금 완료 시점을 서로 다른 엔드포인트로 받아요. 하나만 등록하면 입금 완료가 감지되지 않을 수 있어요.

위 5곳에 없는 PG사(토스·세틀뱅크·이지페이·헥토·스마트로 등)는 계약 PG사와 부트페이 기술 지원으로 통지 URL을 확인한 뒤 같은 방식으로 등록해요.

웹훅 수신 서버는 이렇게 만들어요

웹훅을 안정적으로 처리하려면 아래 세 가지를 같이 맞춰요.

• HTTP 200 + { "success": true } 를 먼저 빠르게 반환해요. 두 조건 중 하나라도 빠지면 부트페이는 실패로 보고 재시도해요.
• 실제 비즈니스 로직(주문 상태 변경, 재고 차감, 알림 발송 등)은 200 반환 이후 비동기로 처리해요.
• 같은 이벤트가 여러 번 들어올 수 있으니 receipt_id 기준으로 멱등 처리​​를 걸어요. 재시도가 반복돼도 주문이 중복 확정되지 않아야 해요.

부트페이는 웹훅이 실패하면 지수 백오프로 자동 재시도해요.

설정 화면도 같이 확인해야 해요

가상계좌 운영 중에 "입금이 됐는데 완료 처리가 안 돼요"라는 이슈는 대부분 설정 누락에서 시작해요. 실무에서는 결국 두 가지를 같이 봐요.

• 입금통보 URL을 어느 화면에 어느 값으로 넣었는지
• 실제 입금 시 Webhook 통지 로그​​에 어떤 응답이 남았는지

부트페이 관리자 > 개발자 설정 > 웹훅 설정 화면

웹훅 URL과 Content-Type을 설정하는 모달

결제내역에서 Webhook 통지 로그로 들어가는 진입 버튼

Webhook 통지 로그에서 실제 전송 결과를 확인하는 화면

그래서 가상계좌를 붙일 때는 아래 순서로 점검해요.

1. 부트페이 관리자에서 웹훅 URL(HTTPS)을 등록해요.
2. 사용하는 PG사 전산에서 가상계좌 입금통보 URL​​을 함께 등록해요. 위 표의 PG사라면 바로 등록하고, 그 외 PG사는 계약 PG와 부트페이 기술 지원으로 URL을 확인해 등록해요.
3. 테스트 입금 후 결제내역의 Webhook 통지 로그​​에서 status: 2(발급)와 status: 1(입금 완료)이 정상 수신되는지 확인해요.

테스트 모드(Sandbox)에서는 발급된 계좌로 실제 입금이 되지 않아요. 입금 시나리오를 검증하려면 결제 요청에 extra.test_deposit: true를 넣어 모의 입금​​으로 웹훅까지 확인해요. 모의 입금은 실제 돈이 빠지지 않으면서 status: 1 이벤트를 발생시켜요.

핵심은 안내는 프론트에서 하고, 확정은 서버에서 한다​​는 점, 그리고 PG·부트페이·가맹점 설정 세 곳이 모두 맞아야 한다​​는 점이에요.

4입금 기한과 만료 처리까지 같이 설계해야 해요

가상계좌는 발급만 되고 끝까지 입금이 안 들어오는 경우가 많아요. 그래서 운영에서 중요한 건 "결제가 느리예요"가 아니라 미입금 주문을 언제 닫을지​​를 정하는 일이에요.

입금 기한이 지나면 주문은 자동 취소되어야 하고, 점유 중이던 재고나 예약 자원도 함께 풀려야 해요. 이 흐름이 없으면 오래된 미입금 주문이 계속 남고, CS도 같은 질문을 반복해서 받게 돼요.

고객 안내도 상태에 맞게 나눠야 해요.

• 발급 직후: 계좌 정보 + 입금 기한 안내
• 만료 전: 입금 필요 리마인드
• 만료 후: 주문 취소 + 재주문 유도

가상계좌는 느린 결제가 아니라 시간차가 있는 결제​​예요. 입금 전, 입금 완료, 만료 후를 각각 다른 상태로 설계해야 운영이 편해져요.

실제로 붙이려면

별도 승인 구조를 적용할 때는 승인 분리와 서버 검증을 함께 확인해요.

• 별도 승인 — /payment-window/separately-confirmed
• 서버 검증 — /server/verify

더 읽기