연동 준비하기

안심선불 연동을 시작하기 전에 알아야 할 준비사항과 기본 정보를 안내합니다.

환경별 키 정보

테스트베드와 상용 환경은 분리되어 있으며, 각각 별도의 상점 ID를 사용합니다.

환경	상점 ID	용도
테스트베드	공용 테스트 상점ID	개발 및 테스트
상용 환경	가맹점 전용 상점ID	실제 운영 서비스

가맹점 전용 키 발급 (계약 후)

헥토파이낸셜과 계약 후 상용 환경에서 사용할 다음 정보를 발급받습니다.

항목	설명
상점 ID (mId)	가맹점 고유 식별자
AES 암호화 키	개인정보 및 중요정보 암복호화 키 (32byte)
SHA-256 해시 키	위변조 방지 해시 생성 키

NOTE

키 발급

테스트베드 공용 키와 상용 환경 가맹점 고유 키는 서비스 이행 시 별도로 통보됩니다.

서버 연동 환경

서버 주소 및 네트워크 정보

안심선불은 UI 서버와 API 서버로 구분됩니다.

UI (MNG)

회원가입 및 내정보 페이지에 사용합니다.

환경	도메인	IP 주소	프로토콜
테스트베드	tb-mps.hectofinancial.co.kr	61.252.169.99	HTTPS(TCP/443)
상용	mps.hectofinancial.co.kr	14.34.14.47 (Main) 61.252.169.103 (DR)	HTTPS(TCP/443)

API

잔액조회, 사용, 충전, 출금 등 API 호출에 사용합니다.

환경	도메인	IP 주소	프로토콜
테스트베드	tb-mps-api.hectofinancial.co.kr	61.252.169.100	HTTPS(TCP/443)
상용	mps-api.hectofinancial.co.kr	14.34.14.48 (Main) 61.252.169.104 (DR)	HTTPS(TCP/443)

NOTE

IDC 이중화 구성

• 헥토파이낸셜 안심선불 시스템은 주센터(Main)와 보조센터(DR)로 이중화되어 있습니다. • Main 센터 장애 시 DR로 자동 전환되므로, 상용 환경의 Main/DR IP 모두 방화벽에서 허용해야 합니다. • DNS Lookup 접속 권장 - 센터 전환 시 자동으로 처리됩니다.

TLS 버전

TLS 1.2 이상 사용을 강력히 권장합니다. TLS 1.1 이하는 보안권고사항에 따라 사전 통지 없이 지원이 중단될 수 있습니다.

개발 환경 요구사항

안심선불은 UI 연동과 API 연동 두 가지 방식을 모두 사용합니다.

구분	역할
프론트엔드	회원가입/내정보 UI 페이지 연동
백엔드 (필수)	잔액조회, 사용, 충전, 출금 등 API 호출

NOTE

UI + API 혼합 연동

• UI 연동: 회원가입 및 내정보 페이지는 헥토파이낸셜 제공 화면 사용 • API 연동: 선불금 사용, 충전, 출금 등은 가맹점 백엔드에서 API 호출

API 연동 정보

안심선불 API는 JSON 형식의 REST API입니다.

구분	내용
인코딩	UTF-8
메소드	POST
데이터 형식	application/json; charset=UTF-8
프로토콜	HTTPS (TLS 1.2 이상)

보안 및 암호화

안심선불은 개인정보 보호를 위해 AES 암호화와 SHA-256 해시를 사용합니다.

AES 암호화 (개인정보)

항목	내용
알고리즘	AES-256/ECB/PKCS5Padding
인코딩	Base64 Encoding
대상 필드	CI값, 거래금액, 고객명, 휴대폰번호, 생년월일, 핀번호 등

암호화 예시:

구분	값
암호화 키	`SETTLEBANKISGOODSETTLEBANKISGOOD` (32byte)
원문	`1234567890abcdef`
암호화 값	`ojTD5p0w4oi2UgEozPuKoZa98R6rydxUF4PH0EikbVo=`

빈 문자열 암호화 금지

공백 또는 빈 문자열을 암호화할 경우 A-001 에러가 발생합니다.

SHA-256 해시 (위변조 방지)

항목	내용
알고리즘	SHA-256
인코딩	Hex Encoding
용도	pktHash 생성 (요청 데이터 위변조 검증)

해시 생성 예시:

구분	값
해시 키	`ST7777777777777777777`
원문	`20241024 + TEST + ST7777777777777777777` (reqDt + data + HashKey)
해시 값	`2f3e6b50773293a4ca25957a27a85dfc7a5f4b245c526e2fee657ce64770c85b`

연동 방식

안심선불은 UI 연동과 API 연동을 함께 사용합니다.

구분	설명	용도
UI 연동	헥토파이낸셜 제공 화면 사용	회원가입, 내정보 관리
API 연동	가맹점 서버에서 직접 API 호출	잔액조회, 사용, 충전, 출금

NOTE