연동 준비하기
간편현금결제(오픈뱅킹) API 연동을 시작하기 전에 알아야 할 준비사항과 기본 정보를 안내합니다.
환경별 키 정보
테스트베드와 상용 환경은 분리되어 있으며, 각각 별도의 상점 ID와 키를 사용합니다.
| 환경 | 상점 ID | 인증 키 | 용도 |
|---|---|---|---|
| 테스트베드 | 공용 테스트 상점ID | 공용 테스트 키 | 개발 및 테스트 (실제 이체 발생 안 함) |
| 상용 환경 | 가맹점 전용 상점ID | 가맹점 전용 키 | 실제 운영 서비스 (실제 이체 발생) |
가맹점 전용 키 발급 (계약 후)
헥토파이낸셜과 계약 후 상용 환경에서 사용할 다음 정보를 발급받습니다.
| 항목 | 설명 |
|---|---|
| 상점 ID (mchtId) | 가맹점 고유 식별자 |
| 해시 생성 키 | 위변조 방지용 해시 생성 키 (SHA-256) |
| 암호화 키 | 개인정보 및 중요정보를 보호하는 키 (AES-256) |
NOTE
영업 담당자를 통한 발급
테스트 환경 및 운영 환경의 상점 ID, 암호화 키, 해시 생성 키는 헥토파이낸셜 영업 담당자를 통해 발급받아야 합니다. 본 연동 규격서에 명시된 키 정보는 설명을 위한 예시 데이터입니다.
서버 연동 환경
서버 주소 및 네트워크 정보
간편현금결제 API는 서버에서 JSON 형식으로 직접 호출합니다.
계좌관리, 이체서비스, 조회서비스 API 모두 동일한 서버 환경을 사용합니다.
| 환경 | 도메인 | IP 주소 | 프로토콜 |
|---|---|---|---|
| 테스트베드 | tbnpay.settlebank.co.kr | 61.252.169.31 | HTTPS(TCP/443) |
| 상용 | npay.settlebank.co.kr | 61.252.169.27 (Primary) 14.34.14.24 (Secondary) | HTTPS(TCP/443) |
NOTE
IDC 이중화 구성
• 헥토파이낸셜 간편현금결제 시스템은 주센터(Primary)와 보조센터(Secondary)로 이중화되어 있습니다.
• Primary 센터 장애 시 Secondary로 자동 전환되므로, 상용 환경의 Primary/Secondary IP 모두 방화벽에서 허용해야 합니다.
• DNS Lookup 접속 권장 - 센터 전환 시 자동으로 처리됩니다 (hosts 파일 고정 시 전환 불가)
개발 환경 요구사항
간편현금결제 연동은 백엔드 서버가 필요합니다.
| 구분 | 역할 |
|---|---|
| 백엔드 (필수) | 해시 생성, 개인정보 암호화, 결제 처리, 결과 검증 |
| 프론트엔드 | 본인인증 화면 호출 (필요시) |
백엔드 서버 필수
보안상 해시 생성과 개인정보 암호화는 반드시 서버에서 처리해야 합니다. 순수 프론트엔드만으로는 간편현금결제 연동이 불가능합니다.
암복호화 및 위변조 방지
간편현금결제는 데이터 보호를 위해 2가지 방식의 보안을 사용합니다.
개인정보 및 중요정보 암복호화
개인정보와 중요정보를 보호하기 위한 암호화 방식입니다.
| 구분 | 내용 |
|---|---|
| 알고리즘 | AES-256 / ECB / PKCS5Padding |
| 인코딩 | Base64 Encoding |
| 암호화 대상 | 담당자명, 유선번호, 휴대폰번호, 이메일, 예금주명, 계좌번호 등 |
| 테스트베드 키 | pgSettle30y739r82jtd709yOfZ2yK5K (32byte) |
| 상용 환경 키 | 계약 후 별도 발급 |
위변조 방지 알고리즘
데이터 무결성을 검증하기 위한 해시 생성 방식입니다.
| 구분 | 내용 |
|---|---|
| 알고리즘 | SHA-256 |
| 인코딩 | Hex Encoding |
| 테스트베드 키 | ST1009281328226982205 (21byte) |
| 상용 환경 키 | 계약 후 별도 발급 |
| 생성 방법 | 파라미터 조합 → SHA-256 해시 → Hex 변환 |
해시 검증 필수
• 요청: 해시 생성하여 전송 필수 (미일치 시 요청 거부)
• 응답: 해시 검증 후 서비스 제공 (미검증 시 위변조 공격 위험)
주의사항
운영환경 테스트 주의
운영 환경 테스트
운영환경에서 테스트가 필요한 경우 헥토파이낸셜 담당자와 협의가 필요합니다. 사전협의 없이 진행되는 운영테스트 거래로 발생하는 비용은 가맹점 부담입니다.
API 요청 주의사항
- POST method만 사용 - 모든 API는 POST 메서드만 지원
- JSON 형식 - 요청/응답 모두 application/json;charset=UTF-8
- 특수문자 제한 -
:,&,?,',new line,<,>기호는 전달 불가 - 파라미터 검증 - 필수값 누락, 해시 불일치, 길이 초과 시 오류 응답
{
"outStatCd": "0031",
"outRsltCd": "ST09",
"outRsltMsg": "유효하지 않는 요청전문"
}
응답 파라미터 변동 가능
응답 파라미터 변동 가능
응답 파라미터는 예고 없이 변동될 수 있으며, 개발시 파라미터 변동에 따른 영향이 발생하지 않도록 개발해 주세요.
네트워크 및 프로토콜 요구사항
- TLS 1.2 이상 필수 - HTTPS(포트 443)만 가능
- 타임아웃 - API 응답 타임아웃은 30초 적용
- 방화벽 설정 - 상용 환경의 Primary/Secondary IP 모두 허용 필요
- hosts 파일 고정 지양 - IDC 센터 전환 시 자동 대응 불가
