결제창 연동
헥토파이낸셜 결제창은 신용카드, 계좌이체, 가상계좌, 휴대폰 결제 등 다양한 결제수단을 통합 제공하는 표준 결제 UI입니다.
연동 방식
결제창을 호출하는 방법은 두 가지가 있습니다.
| 방식 | 설명 |
|---|---|
| JavaScript SDK | SettlePG.js SDK를 사용하여 결제창 호출 |
| FORM-SUBMIT | HTML Form을 직접 생성하여 결제창 호출 |
두 방식 모두 동일한 결제창을 호출하며, 동일한 파라미터를 사용합니다.
방식별 특징
JavaScript SDK
// SDK 스크립트 로드
<script src="https://tbnpg.settlebank.co.kr/resources/js/v1/SettlePG_v1.2.js"></script>
// 결제 호출
SETTLE_PG.pay({
env: "https://tbnpg.settlebank.co.kr",
ui: { type: "popup", width: 430, height: 660 },
mchtId: "nxca_jt_il",
method: "card",
// ... 결제수단별 파라미터
}, callback);
특징:
- JavaScript 함수 호출로 간편하게 결제창 호출
- popup, self, blank 등 다양한 UI 타입 지원
- Form 생성 및 제출을 SDK가 자동 처리
FORM-SUBMIT
<form method="POST" action="https://tbnpg.settlebank.co.kr/card/main.do" target="_blank">
<input type="hidden" name="mchtId" value="nxca_jt_il" />
<input type="hidden" name="method" value="card" />
<!-- ... 결제수단별 파라미터 -->
</form>
특징:
- HTML Form을 직접 구성하여 결제창 호출
- SDK 의존성 없이 연동 가능
- 결제수단별 Action URL 직접 지정 필요
결제창 UI 타입
| 타입 | 설명 | SDK | FORM |
|---|---|---|---|
popup | 팝업 창으로 결제창 표시 | O | O |
iframe | 현재 페이지 내 레이어로 표시 | O | - |
self | 현재 창에서 결제창으로 이동 | O | O |
blank | 새 창에서 결제창 표시 | O | O |
iframe 방식은 지양하세요
iframe 방식은 로컬 네트워크 접근 제한, 브라우저 호환성 문제 등의 이슈가 있어 권장하지 않습니다. popup, self, blank 방식 사용을 권장합니다.
결제 흐름
고객
가맹점
결제창
헥토파이낸셜
1결제 요청
결제 요청
2결제창 호출
결제창 호출
3결제창 표시
결제창 표시
4결제정보 입력
결제정보 입력
5인증/승인 요청
인증/승인 요청
6결과 반환
결과 반환
7결과 통보 (notiUrl)
결과 통보 (notiUrl)
결제 성공 시: nextUrl로 리다이렉트되어 결과가 전달되고, notiUrl로 서버 통보가 전송됩니다.
결제 실패/취소 시: cancUrl로 리다이렉트됩니다.
NOTE
notiUrl 필수
nextUrl은 브라우저를 통해 전달되므로 네트워크 오류로 누락될 수 있습니다. 실제 주문 처리는 반드시 notiUrl(Server-to-Server)에서 수행해야 합니다.
자세한 설명은 결과통보 URL 가이드를 참고하세요.
연동 준비
결제창 호출 전 백엔드에서 다음 처리가 필수입니다.
서버 사이드 처리
SDK와 FORM 방식 모두 동일하게 다음 처리를 서버에서 수행해야 합니다:
- 거래금액 암호화: AES-256 방식으로 암호화
- 위변조 방지 해시: SHA-256 방식으로 pktHash 생성
NOTE
암호화 및 해시 생성 규칙
AES-256 암호화 규칙, SHA-256 해시 생성 순서, 테스트 키 정보는 연동 준비하기 문서를 참고하세요. 연동 준비하기 — 암복호화 및 위변조 방지
보안 주의
암호화 키와 해시 키는 반드시 서버에서만 사용해야 합니다. 클라이언트에 노출하면 안 됩니다.
