JavaScript SDK 연동 API
헥토파이낸셜 JavaScript SDK(SettlePG)를 사용하여 결제창을 연동하는 방법을 설명합니다.
주의 사항
결제창 타임아웃
SDK 스크립트 로드
<!-- 테스트 환경 -->
<script src="https://tbnpg.settlebank.co.kr/resources/js/v1/SettlePG_v1.2.js"></script>
<!-- 운영 환경 -->
<script src="https://npg.settlebank.co.kr/resources/js/v1/SettlePG_v1.2.js"></script>
SETTLE_PG.pay()
SETTLE_PG.pay(options, callback);
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
options | Object | O | 결제 요청 파라미터 (아래 상세 참고) |
callback | Function | - | iframe 방식에서 결과 수신 콜백 |
스크립트 파라미터 정의
SETTLE_PG.pay()의 options 객체에 전달하는 파라미터입니다. SDK는 env, ui와 필수 파라미터(mchtId, method, mchtTrdNo, trdDt, trdTm, trdAmt, mchtName, pmtPrdtNm, notiUrl, nextUrl, cancUrl, pktHash)가 비어 있는지, method 값이 올바른지를 검증하며, 나머지 파라미터는 서버에서 검증됩니다.
결제수단별 추가 파라미터(카드사명, 가상계좌번호 등)는 결제창 연동 문서를 참고하세요.
주문 처리 주의
필수 파라미터
https://tbnpg.settlebank.co.kr테스트: https://tbnpg.settlebank.co.kr 운영: https://npg.settlebank.co.krnxca_jt_ilcardcard: 신용카드 bank: 계좌이체 vbank: 가상계좌 vbank010: 010가상계좌 mobile: 휴대폰결제 tmoney: 티머니 point: 포인트다모아 corp: 간편결제 teencash: 틴캐시 culturecash: 컬쳐캐쉬 smartcash: 스마트문상 booknlife: 도서상품권20240101153045ORDER2024010115304510000https://example.com/api/payment/notihttps://example.com/payment/successabc123...헥토파이낸셜노트북 구매https://example.com/payment/cancel{ type: "popup", width: 430, height: 660 }선택 파라미터
authdirect: 신용카드 직호출 (/card/cardDirect.do) auth: 카드등록(빌키발급) 결제창 (/card/cardAuth.do)Hecto Financial홍길동신한 1234-56-7890name=Hong&age=25127.0.0.1ui 객체 파라미터
popuppopup: 팝업창 iframe: 레이어 self: 현재창 blank: 새창430660UI 타입별 동작
SDK의 ui.type 옵션으로 결제창 표시 방식을 지정합니다.
popup (팝업)
SETTLE_PG.pay({
env: "https://tbnpg.settlebank.co.kr",
ui: { type: "popup", width: 430, height: 660 },
// ... 결제수단별 파라미터
}, null);
- 별도 팝업 창에서 결제창 표시
- 팝업 차단 시 안내 메시지 표시
- 결제 완료 후
nextUrl로 리다이렉트
iframe (레이어) ⚠️
iframe 방식은 지양하세요
SETTLE_PG.pay({
env: "https://tbnpg.settlebank.co.kr",
ui: { type: "iframe", width: 430, height: 660 },
// ... 결제수단별 파라미터
}, function(response) {
// 결과 수신
if (response.outStatCd === "0021") {
console.log("성공:", response.trdNo);
} else {
console.log("실패:", response.outRsltMsg);
}
});
- 현재 페이지 위에 dimmed 레이어와 함께 결제창 표시
- 콜백 함수로 결제 결과 수신 (iframe만 해당)
iframe 콜백은 화면 표시용
콜백 응답 파라미터
iframe 방식에서 콜백 함수로 전달되는 response 객체의 주요 파라미터입니다.
| 파라미터 | 타입 | 설명 |
|---|---|---|
outStatCd | AN(4) | 거래상태 코드 (0021: 성공, 0031: 실패, 0041: 대기, 0051: 진행중) |
outRsltCd | AN(4) | 상세 결과 코드 |
outRsltMsg | AHN(200) | 결과 메시지 |
trdNo | AN(40) | 헥토파이낸셜 거래번호 |
mchtTrdNo | AN(100) | 상점 주문번호 |
trdAmt | N(12) | 거래금액 |
method | A(10) | 결제수단 코드 |
self (현재 창)
SETTLE_PG.pay({
env: "https://tbnpg.settlebank.co.kr",
ui: { type: "self" },
// ... 결제수단별 파라미터
}, null);
- 현재 창에서 결제 페이지로 이동
- 결제 완료 후
nextUrl로 리다이렉트 - 뒤로가기 시
cancUrl로 이동
blank (새 창)
SETTLE_PG.pay({
env: "https://tbnpg.settlebank.co.kr",
ui: { type: "blank" },
// ... 결제수단별 파라미터
}, null);
- 새 탭/창에서 결제창 표시
- 팝업과 유사하나 브라우저 기본 새 창 동작 사용
서버 사이드 처리
SDK 호출 전 백엔드에서 거래금액 암호화(AES-256)와 위변조 방지 해시(SHA-256)를 생성해야 합니다.
상세 정보: 연동 준비하기 — 암복호화 및 위변조 방지
에러 처리
SDK는 아래 두 가지 경우에 브라우저 alert을 표시합니다.
팝업 차단
[헥토파이낸셜] 팝업 차단 설정이 되어 있습니다. 해제 후 다시 이용해 주세요.
팝업 차단 해제 방법:
- Chrome: 주소창 우측 팝업 차단 아이콘 클릭 → '항상 허용'
- Safari: 환경설정 → 웹사이트 → 팝업 윈도우 → '허용'
- Edge: 설정 → 쿠키 및 사이트 권한 → 팝업 및 리디렉션 → 허용
필수 파라미터 누락
env, ui 또는 필수 파라미터(mchtId, method, mchtTrdNo, trdDt, trdTm, trdAmt, mchtName, pmtPrdtNm, notiUrl, nextUrl, cancUrl, pktHash)가 비어 있거나 method 값이 올바르지 않으면 alert을 표시합니다.
서버 검증
[헥토파이낸셜] 호출 파라미터 오류 (mchtId is null)
결제수단별 파라미터
SDK 연동 방법은 모든 결제수단에서 동일합니다. 각 결제수단별 상세 파라미터는 왼쪽 메뉴의 결제수단별 연동 문서를 참고하세요.
