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);

스크립트 파라미터 정의

SETTLE_PG.pay()의 options 객체에 전달하는 파라미터입니다. SDK는 env, mchtId, method, ui만 검증하며, 나머지 파라미터는 서버에서 검증됩니다.

결제수단별 추가 파라미터(카드사명, 가상계좌번호 등)는 결제창 연동 문서를 참고하세요.

필수 파라미터

선택 파라미터

ui 객체 파라미터

UI 타입별 동작

SDK의 ui.type 옵션으로 결제창 표시 방식을 지정합니다.

popup (팝업)

SETTLE_PG.pay({
    env: "https://tbnpg.settlebank.co.kr",
    ui: { type: "popup", width: 430, height: 660 },
    // ... 결제수단별 파라미터
}, null);

• 별도 팝업 창에서 결제창 표시
• 팝업 차단 시 안내 메시지 표시
• 결제 완료 후 nextUrl로 리다이렉트

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 방식에서 콜백 함수로 전달되는 response 객체의 주요 파라미터입니다.

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: 설정 → 쿠키 및 사이트 권한 → 팝업 및 리디렉션 → 허용

필수 파라미터 누락

필수 파라미터(mchtId, env, method, ui)가 누락되면 alert을 표시합니다.

결제수단별 파라미터

SDK 연동 방법은 모든 결제수단에서 동일합니다. 각 결제수단별 상세 파라미터는 왼쪽 메뉴의 결제수단별 연동 문서를 참고하세요.

더 궁금한 내용이 있나요?

FAQ

기술지원이 필요한가요?

pgsupport@hecto.co.kr

코드 샘플

HectoFinancial GitHub