연동 준비하기
PG API 연동을 시작하기 전에 알아야 할 준비사항과 기본 정보를 안내합니다.
환경별 키 정보
테스트베드와 상용 환경은 분리되어 있으며, 각각 별도의 상점 ID와 키를 사용합니다. 테스트베드는 공용 테스트 키를 사용하고, 상용 환경은 가맹점 전용 키를 사용합니다.
| 환경 | 상점 ID | 인증 키 | 용도 |
|---|---|---|---|
| 테스트베드 | 공용 테스트 상점ID | 공용 테스트 키 | 개발 및 테스트 (실제 결제 발생 안 함) |
| 상용 환경 | 가맹점 전용 상점ID | 가맹점 전용 키 | 실제 운영 서비스 (실제 결제 발생) |
가맹점 전용 키 발급 (계약 후)
헥토파이낸셜과 계약 후 상용 환경에서 사용할 다음 정보를 발급받습니다.
| 항목 | 설명 |
|---|---|
| 상점 ID (mchtId) | 가맹점 고유 식별자 |
| 라이센스 키 | 해시 생성 키 |
| 암호화 키 | 거래금액, 개인정보 등을 보호하는 키 (AES-256) |
발급받은 키 확인 방법
발급받은 키는 가맹점관리자 사이트에서 직접 확인할 수 있습니다. 가맹점관리자 사이트 접속 주소와 계정은 영업 담당자를 통해 전달받습니다.
- 가맹점관리자 사이트 좌측 메뉴에서 [가맹점 정보] → [기본정보] 메뉴를 누릅니다.
- 기본정보 페이지 상단의 [라이센스&암호화키 정보] 영역에서 라이센스 키와 암호화 키를 확인합니다.
NOTE
접속 정보 문의
가맹점관리자 사이트 접속 주소·계정, 키 발급 관련 문의는 영업 담당자에게 해 주세요.
서버 연동 환경
서버 도메인, IP 주소, 방화벽 설정 정보는 서버 및 네트워크 정보 문서를 참고하세요.
개발 환경 요구사항
PG 연동은 프론트엔드와 백엔드가 모두 필요합니다.
| 구분 | 역할 |
|---|---|
| 백엔드 (필수) | 해시 생성, 금액 암호화, 결과 검증 |
| 프론트엔드 | 백엔드에서 생성한 암호화 데이터로 결제창 호출 (SDK 또는 FORM) |
백엔드 필수
보안상 해시 생성과 금액 암호화는 반드시 서버에서 처리해야 합니다. 순수 프론트엔드만으로는 결제 연동이 불가능합니다.
암복호화 및 위변조 방지
PG 결제(결제창 호출 포함)는 데이터 보호를 위해 2가지 방식의 보안을 사용합니다. 결제창 방식과 API 방식 모두 동일하게 적용됩니다.
개인정보 및 중요정보 암복호화
개인정보와 중요정보를 보호하기 위한 암호화 방식입니다.
| 구분 | 내용 |
|---|---|
| 알고리즘 | AES-256 / ECB / PKCS5Padding |
| 인코딩 | Base64 Encoding |
| 암호화 대상 | 거래금액, 고객명, 휴대폰번호, 이메일, 카드번호, 계좌번호 등 |
| 테스트베드 키 | pgSettle30y739r82jtd709yOfZ2yK5K |
| 상용 환경 키 | 계약 후 별도 발급 |
위변조 방지 알고리즘 (pktHash)
데이터 무결성을 검증하기 위한 해시 생성 방식입니다.
| 구분 | 내용 |
|---|---|
| 알고리즘 | SHA-256 |
| 인코딩 | Hex Encoding |
| 테스트베드 키 | ST1009281328226982205 |
| 상용 환경 키 | 계약 후 별도 발급 |
| 생성 방법 | 파라미터 조합 → SHA-256 해시 → Hex 변환 |
pktHash 검증 필수
• 요청: pktHash 생성하여 전송 필수 (미일치 시 요청 거부)
• 응답: pktHash 검증 후 서비스 제공 (미검증 시 위변조 공격 위험)
주의사항
운영환경 테스트 주의
- 운영환경 테스트 주의: 운영환경에서 테스트 시 발생하는 비용은 가맹점 부담입니다. 반드시 테스트베드에서 테스트를 완료해야 합니다.
API 요청 주의사항
- POST method만 사용
- 연동규격서에 명시된 파라미터만 사용
- 특수문자, HTML 태그, 이모지 사용 금지
- mchtTrdNo는 1일 단위(00:00~24:00)로 중복 체크
프론트엔드 연동 주의사항
- iframe 사용 자제 (일부 브라우저에서 오작동)
- notiUrl, nextUrl, cancUrl은 HTTPS 권장
- DB 처리는 반드시 notiUrl에서 수행 (nextUrl은 화면 처리용)
브라우저 및 프로토콜 요구사항
- TLS 1.2 이상 필수
- HTTPS(포트 443)만 가능, HTTP 미지원
- 안전한 암호화 통신 보장
- 지원 브라우저: Chrome, Edge, Firefox, Safari
- 미지원 브라우저: Internet Explorer (지원 종료), Opera
