Finance / Banking API
Pharos ERP KB 기업뱅킹 이체 서비스 연동
- Java 11
- Spring Boot 2.7
- Spring Security
- Spring Data Redis
- MyBatis
- PostgreSQL
- NHN Cloud VPN
- Jenkins
Overview
Pharos ERP 금융관리 기능으로 KB국민은행 Open API를 연동해 일반·대금·급여 이체 서비스를 구현했습니다. 기업뱅킹 연동 등록, 양자 인증, 본인인증 기반 3자 인증, 이체 실행과 이력 관리를 구성했습니다.
Problem
- 양자 인증 토큰과 3자 인증 토큰의 발급 조건, 재사용 기준, 캐시 키가 서로 달라 토큰 관리 전략이 필요했습니다.
- 일반, 대금, 급여 이체 유형별 처리 방식과 결과 조회 방식이 달라 중복 방지와 상태 업데이트 기준을 분리해야 했습니다.
- 운영 배포 후 VPN 통신에서 간헐적 Connection Timeout과 Read Timeout이 발생해 네트워크 레벨 원인 분석이 필요했습니다.
My Ownership
- KB Open API 인증·조회·이체 API 연동과 Redis 기반 토큰 관리 전략을 구현했습니다.
- KB, NHN Cloud 담당자와 커뮤니케이션하며 VPN 통신 이슈의 원인 범위를 네트워크와 애플리케이션 연결 재사용까지 확장해 분석했습니다.
- 이체 실행과 이력 저장을 도메인 이벤트로 분리해 영속화 실패가 이체 응답에 전파되지 않도록 했습니다.
Key Decisions
토큰 저장Redis 캐싱
양자 인증 토큰은 기관 ID 기준으로 재사용하고, 3자 인증 토큰은 기관 ID와 MAC 주소를 기준으로 독립 관리했습니다.
은행별 분기전략 패턴
KB, 신한, NH 은행별 등록·삭제 처리 차이를 전략 구현체로 분리해 은행 추가 시 기존 코드를 덜 수정하도록 했습니다.
이체 이력도메인 이벤트 비동기 처리
이체 실행 응답과 이력 영속화를 분리해 영속화 실패가 핵심 이체 흐름에 영향을 주지 않게 했습니다.
Implementation
기업뱅킹 인증 플로우
KB 고객 여부 확인, 양자 인증 토큰 발급, 본인인증 URL 발급, 3자 인증 토큰 콜백 수신 흐름을 구현했습니다.
이체 처리
10건 이하 일반 이체는 즉시 처리 후 통합 결과 조회를 수행하고, 10건 초과·대금·급여 이체는 별도 결과 조회로 상태를 업데이트했습니다.
VPN 통신 이슈 분석
tcpdump 패킷 덤프, IPsec Traffic Selector, WebClient Idle Time과 NLB Idle Timeout을 함께 분석해 KB API 전용 연결 설정을 조정했습니다.
Detailed Notes
기업뱅킹 연동 설정
- 전략 패턴으로 KB·신한·NH 은행별 등록·삭제 처리 분기를 구성해 새로운 은행 추가 시 기존 코드 수정을 줄였습니다.
- 일급 컬렉션으로 연동된 은행 목록을 관리해 KB·신한·NH 연동 여부를 단일 지점에서 확인하고, 동일 은행 중복 등록 시 즉시 예외 처리했습니다.
- 연동 등록 시 해당 은행 뱅킹 메뉴 권한을 자동 부여하고, 연동 해제 시 권한을 일괄 삭제했습니다.
KB 인증 플로우와 토큰 관리
KB 고객 여부 확인 → 양자 인증 토큰 발급 → 양자 토큰으로 본인인증 URL 발급 → KB 본인인증 완료 후 3자 인증 토큰 콜백 수신 흐름을 구현했습니다.
| 구분 | 양자 인증 토큰 | 3자 인증 토큰 |
|---|---|---|
| 발급 조건 | KB 고객 여부 확인 후 발급 | 본인인증 완료 시 KB 콜백으로 발급 |
| Redis 키 | 기관 ID 기반 | 기관 ID + MAC 주소 기반 |
| 재사용 | TTL 만료 전 재사용 | MAC 주소 변경 감지 시 재발급 |
| 용도 | 3자 인증 토큰 발급용 | 뱅킹 업무 API 호출 |
MAC 주소 수집과 API 요청자 추상화
- 안랩 ASTx2 MAC 주소 수집 모듈이 JSP만 지원해 별도 서버를 운영했습니다.
- 멀티 서버 환경에서 정확한 MAC 주소를 수집하기 위해 SHA-256 암호화 기반 서버별 고유 ID를 설정했습니다.
- 프론트에서 iframe으로 연동할 수 있도록 CORS 설정과 postMessage를 구현했습니다.
- KB API 요청자를 인터페이스로 추상화해 VPN 환경 여부에 따라 게이트웨이 엔드포인트를 분기했습니다.
- KB API 에러 응답을 커스텀 예외로 변환 처리했습니다.
이체 유형별 처리와 이력 관리
- 이체 실행 시 Session과 OTT(One-Time Token)를 추가 발급해 요청마다 일회성 검증을 수행했습니다.
- 연결 ID(전표 번호·장부 번호·지출결의서 ID) 기반 이전 이체 상태를 확인해 진행 중이면 즉시 예외 처리했습니다.
- 도메인 이벤트 기반 이체 이력 비동기 저장으로 이벤트 스토어·로그를 선적재하고, 영속화 실패 시 텔레그램 알림과 이벤트 스토어 기반 재처리를 가능하게 했습니다.
| 이체 유형 | 처리 방식 |
|---|---|
| 일반 이체 (10건 이하) | 즉시 처리 후 통합이체결과 조회로 상태 확인 |
| 일반 이체 (10건 초과) | 이체 요청 후 별도 결과 조회로 상태 업데이트 |
| 대금 이체 · 급여 이체 | 이체 요청 후 별도 결과 조회로 상태 업데이트 |
VPN 통신 이슈 원인 분석
- 운영 배포 후 KB API 통신에서 간헐적 Connection Timeout과 Read Timeout이 발생했지만, 개발 서버와 기존 외부 API 통신에서는 재현되지 않아 네트워크 레벨 분석을 진행했습니다.
- 6대 서버 tcpdump TCP 패킷 덤프에서 전송 패킷은 확인됐으나 일부 요청에서 3-way handshake 응답이 없고 FIN 패킷으로 연결 종료되는 패턴을 확인했습니다.
- NHN Cloud 아키텍처팀과 IPsec Phase-2 재협상 시 NHN Cloud Proxy-id 0.0.0.0/0과 AWS VPC Specific CIDR Traffic Selector 불일치를 분석했습니다.
- DPD timeout과 Rekey Margin Time 설정 문제를 추가 확인했습니다.
- 1차로 AWS VPN CIDR을 0.0.0.0/0으로 범용화하고 DPD timeout 60초, Rekey Margin Time 302초로 재조정해 발생 빈도를 줄였습니다.
- 근본 원인으로 WebClient v5 기본 Idle Time 무제한과 NLB Idle Timeout 360초 이후 조용히 종료된 TCP 연결 재사용 문제를 확인했습니다.
- KB API 전용 WebClient Idle Time을 30초로 설정해 NLB Idle Timeout 대비 충분한 마진을 확보하고 정상 통신을 확인했습니다.
Result / Impact
- 양자 인증과 3자 인증 토큰의 Redis 캐싱 전략을 분리했습니다.
- 일반·대금·급여 이체 서비스와 연결 ID 기반 중복 방지 검증을 구현했습니다.
- TCP 패킷 덤프와 네트워크 협업을 통해 VPN 통신 이슈의 원인 범위를 좁히고 정상 통신을 확인했습니다.