연동 준비하기

화이트라벨 API 연동을 시작하기 전에 알아야 할 준비사항과 기본 정보를 안내합니다.

환경별 키 정보

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

환경	상점 ID	인증 키	용도
테스트베드	공용 테스트 상점ID	공용 테스트 키	개발 및 테스트 (실제 결제 발생 안 함)
상용 환경	가맹점 전용 상점ID	가맹점 전용 키	실제 운영 서비스 (실제 결제 발생)

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

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

항목	설명
상점 ID (mchtId)	가맹점 고유 식별자
라이센스 키	해시 생성 키
암호화 키	거래금액, 개인정보 등을 보호하는 키 (AES-256)

서버 연동 환경

서버 주소 및 네트워크 정보

화이트라벨은 결제창(UI) 방식과 API 방식을 모두 지원합니다. 결제창으로 인증 후 서버에서 결제 API를 호출합니다.

결제창

환경	도메인	IP 주소	프로토콜
테스트베드	tbwl.settlebank.co.kr	61.252.169.42	HTTPS(TCP/443)
상용	wl.settlebank.co.kr	61.252.169.53 (Primary) 14.34.14.21 (Secondary)	HTTPS(TCP/443)

API

환경	도메인	IP 주소	프로토콜
테스트베드	tbapi.settlebank.co.kr	61.252.169.42	HTTPS(TCP/443)
상용	api.settlebank.co.kr	61.252.169.53 (Primary) 14.34.14.21 (Secondary)	HTTPS(TCP/443)

NOTE

IDC 이중화 구성

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

개발 환경 요구사항

화이트라벨 연동은 프론트엔드와 백엔드가 모두 필요합니다.

구분	역할
프론트엔드 (필수)	결제창 호출, 결제 결과 수신
백엔드 (필수)	해시 생성, 금액 암호화, 결제/취소 API 호출

백엔드 필수

보안상 해시 생성과 금액 암호화는 반드시 서버에서 처리해야 합니다. 순수 프론트엔드만으로는 결제 연동이 불가능합니다.

암복호화 및 위변조 방지

화이트라벨 결제는 데이터 보호를 위해 2가지 방식의 보안을 사용합니다.

개인정보 및 중요정보 암복호화

개인정보와 중요정보를 보호하기 위한 암호화 방식입니다.

구분	내용
알고리즘	AES-256 / ECB / PKCS5Padding
인코딩	Base64 Encoding
암호화 대상	거래금액, 고객명, 휴대폰번호, 이메일 등
테스트베드 키	pgSettle30y739r82jtd709yOfZ2yK5K
상용 환경 키	계약 후 별도 발급

위변조 방지 알고리즘 (pktHash)

데이터 무결성을 검증하기 위한 해시 생성 방식입니다.

구분	내용
알고리즘	SHA-256
인코딩	Hex Encoding
테스트베드 키	ST1009281328226982205
상용 환경 키	계약 후 별도 발급
생성 방법	파라미터 조합 → SHA-256 해시 → Hex 변환

pktHash 검증 필수

• 요청: pktHash 생성하여 전송 필수 (미일치 시 요청 거부) • 응답: pktHash 검증 후 서비스 제공 (미검증 시 위변조 공격 위험)

주의사항

운영환경 테스트 주의

운영환경 테스트 주의: 운영환경에서 테스트 시 발생하는 비용은 가맹점 부담입니다. 반드시 테스트베드에서 테스트를 완료해야 합니다.

API 요청 주의사항

POST method만 사용
연동규격서에 명시된 파라미터만 사용
특수문자 (:, &, ?, ', <, > 등) 사용 금지
HTML 태그, 이모지 사용 금지
요청 및 응답 파라미터는 예고 없이 변동될 수 있음

프론트엔드 연동 주의사항

iframe 사용 자제 (일부 브라우저에서 오작동)
nextUrl, cancUrl은 HTTPS 권장 (HTTP 사용 시 cross-origin 오류 발생 가능)
nextUrl: 결제 완료 시 호출 (강제 종료 시 미호출)
cancUrl: 사용자가 결제창 'X' 버튼으로 종료 시 호출

브라우저 및 프로토콜 요구사항

TLS 1.2 이상 필수
- HTTPS(포트 443)만 가능, HTTP 미지원
- TLS 1.1 이하 버전은 사전 통지 없이 지원 중단될 수 있음
지원 브라우저: Chrome, Edge
미지원 브라우저: Internet Explorer, Firefox, Safari, Opera 등