연동 준비하기
실시간 펌뱅킹 연동을 시작하기 전에 알아야 할 준비사항과 기본 정보를 안내합니다.
환경별 키 정보
실시간 펌뱅킹 서비스는 헥토파이낸셜과 계약 후 제공되는 정보로 연동합니다.
| 환경 | 업체번호 | 용도 |
|---|---|---|
| 테스트베드 | 헥토파이낸셜 제공 | 개발 및 테스트 |
| 상용 환경 | 가맹점 전용 업체번호 | 실제 운영 서비스 |
가맹점 전용 키 발급 (계약 후)
헥토파이낸셜과 계약 후 상용 환경에서 사용할 다음 정보를 발급받습니다.
| 항목 | 설명 |
|---|---|
| 업체번호 | 가맹점 고유 식별자 (12자리) |
| 은행코드 | 펌뱅킹 계약된 개설은행코드 (3자리) |
| 서버 IP 및 Port | 연동 서버 접속 정보 |
서버 연동 환경
통신 방식
실시간 펌뱅킹은 TCP/IP 소켓 통신을 사용합니다.
| 구분 | 내용 |
|---|---|
| 프로토콜 | TCP/IP |
| 통신 방식 | 동기/비동기 통신 지원 |
| 전문 형식 | 고정길이 전문 (300 바이트) |
| 세션 유지 | Polling 방식 (기본 5분 간격) |
서버 주소 및 네트워크 정보
실시간 펌뱅킹 서버 접속 정보는 헥토파이낸셜과 계약 후 별도로 제공됩니다.
| 환경 | 서비스 | 접속 정보 |
|---|---|---|
| 테스트베드 | 펌뱅킹 서버 | 헥토파이낸셜 제공 |
| 상용 | 펌뱅킹 서버 | 헥토파이낸셜 제공 (Main/DR 이중화) |
NOTE
IDC 이중화 구성
• 헥토파이낸셜 펌뱅킹 시스템은 주센터(Main)와 보조센터(DR)로 이중화되어 있습니다.
• Main 센터 장애 시 DR로 수동 전환되므로, 양쪽 서버 정보를 모두 보관해야 합니다.
개발 환경 요구사항
실시간 펌뱅킹은 서버 to 서버 TCP/IP 소켓 통신입니다.
| 구분 | 역할 |
|---|---|
| 백엔드 (필수) | TCP/IP 소켓 통신으로 펌뱅킹 전문 송수신 |
NOTE
TCP/IP 소켓 통신
실시간 펌뱅킹은 HTTP 기반이 아닌 TCP/IP 소켓 통신을 사용합니다. 백엔드에서 소켓 연결 및 전문 송수신 로직을 구현해야 합니다.
전문 구조
실시간 펌뱅킹은 고정길이 전문 방식을 사용하며, 원화와 외화 전문의 크기가 다릅니다.
원화 펌뱅킹 전문 구성
| 구성 요소 | 길이 | 설명 |
|---|---|---|
| Length 헤더 | 4 Byte | 전문 전체 길이 ("0300") |
| 공통부 | 100 Byte | 모든 전문 공통 헤더 정보 |
| 개별부 | 200 Byte | 전문별 개별 데이터 |
| 전체 | 304 Byte | Length(4) + 공통부(100) + 개별부(200) |
외화 펌뱅킹 전문 구성
| 구성 요소 | 길이 | 설명 |
|---|---|---|
| Length 헤더 | 4 Byte | 전문 전체 길이 ("2000") |
| 공통부 | 100 Byte | 모든 전문 공통 헤더 정보 (원화와 동일) |
| 개별부 | 1900 Byte | 전문별 개별 데이터 (원화보다 큼) |
| 전체 | 2004 Byte | Length(4) + 공통부(100) + 개별부(1900) |
NOTE
원화 vs 외화 전문 크기
• 원화 펌뱅킹: 304 Byte (개별부 200 Byte)
• 외화 펌뱅킹: 2004 Byte (개별부 1900 Byte)
• 공통부는 원화/외화 모두 100 Byte로 동일합니다.
공통부 주요 항목
| No | 항목 | 위치 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| 1 | 식별코드 | 0 | 9 | Y | 수신자의 TRANSACTION CODE |
| 2 | 업체번호 | 9 | 12 | Y | 헥토파이낸셜에서 부여한 업체번호 |
| 3 | 은행코드 | 21 | 3 | Y | 펌뱅킹 계약된 개설은행코드 |
| 4 | 전문구분코드 | 24 | 4 | Y | 전문코드 (요청/응답) |
| 5 | 업무구분코드 | 28 | 3 | Y | 업무구분 |
| 6 | 송신회수 | 31 | 1 | Y | '1' 고정 |
| 7 | 전문번호 | 32 | 6 | Y | 일별 Unique 전문번호 (MAX 950,000) |
| 8 | 전송일자 | 38 | 8 | Y | 전문전송 일자 (YYYYMMDD) |
| 9 | 전송시간 | 46 | 6 | Y | 전문전송시간 (hhmmss) |
| 10 | 응답코드 | 52 | 4 | - | 응답코드 (에러코드), 요청 시 SPACE |
| 11 | 예비영역 | 56 | 44 | - | 헥토파이낸셜 고유영역 |
고정길이 전문
모든 필드는 정확한 길이를 맞춰야 합니다. 부족한 길이는 SPACE로 채우고, 숫자는 앞을 0으로 채웁니다.
통신 방식
실시간 펌뱅킹은 두 가지 통신 방식을 지원합니다.
| 방식 | 설명 | 적합한 경우 |
|---|---|---|
| 동기 통신 | 거래 건별로 소켓 연결/종료 수행 | 거래 빈도가 낮은 경우 |
| 비동기 통신 | 세션 유지하면서 여러 거래 처리 | 거래 빈도가 높은 경우, 대량 거래 처리 |
NOTE
상세한 통신 흐름
동기/비동기 통신 방식의 상세한 단계별 흐름은 '전체 연동 플로우' 문서를 참고하세요.
주의사항
TCP/IP 통신 주의사항
- 고정길이 전문: 모든 필드는 정확한 길이를 맞춰야 합니다
- 문자셋: EUC-KR 사용
- 숫자 패딩: 숫자 필드는 앞을 0으로 채웁니다
- 문자 패딩: 문자 필드는 뒤를 SPACE로 채웁니다
- 전문번호: 일별 Unique 값 (MAX 950,000)
세션 유지 방식 주의사항
- 업무개시 필수: 매일 업무시작 전 업무개시 전문(1000/100) 송신
- Polling 주기: 5분(300초) 간격으로 Polling 전문 송신
금융기관 업무시간
업무시간 안내
헥토파이낸셜에서는 01:00 ~ 23:30 사이 거래를 권장합니다. 은행별 점검시간은 연장될 수 있습니다.
금융기관별 상세 업무시간은 관리전문 문서를 참고하세요.
