헥토파이낸셜 개발자센터

내통장 결제인증 (결제창)

내통장결제 결제창을 통해 고객의 계좌 인증을 진행합니다. 인증 완료 후 Callback URL로 결과가 전달되며, 이후 결제승인 API를 호출하여 실제 출금을 진행합니다.

테스트용 키 정보

API 정보

POST결제창 연동
Content-Typeapplication/x-www-form-urlencoded
테스트https://tbezauth.settlebank.co.kr
운영https://ezauth.settlebank.co.kr

연동 스크립트

구분URL
테스트베드https://tbezauth.settlebank.co.kr/js/SettlePay.js
상용 환경https://ezauth.settlebank.co.kr/js/SettlePay.js
SettlePay.execute(form);

요청 파라미터

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte

필수 파라미터

└hdInfoAN(50)영문+숫자, 최대 50byte*
전문 정보 코드
*고정값
└apiVerAN(4)영문+숫자, 최대 4byte*
전문 버전
*고정값 (2.0: 리다이렉트 피싱 방지 적용)
└processTypeA(1)영문, 최대 1byte*
처리구분
*고정값
└mercntIdAN(8)영문+숫자, 최대 8byte*
헥토파이낸셜에서 부여하는 고유 상점아이디
└ordNoAN(100)영문+숫자, 최대 100byte*
가맹점에서 생성한 고유 주문번호 (동일 거래일자에 유일성 보장)
└custCiAN(192)영문+숫자, 최대 192byte*AES-256AES-256/ECB/PKCS5Padding + Hex
고객 CI (값이 내통장결제 측 고객 CI와 다를 경우 cancelUrl로 이동)
└trDayN(8)숫자, 최대 8byte*
가맹점에서 주문시 생성한 거래일자 (yyyyMMdd)
└trTimeN(6)숫자, 최대 6byte*
가맹점에서 주문시 생성한 거래시각 (HH24MISS)
└trPriceAN(13)영문+숫자, 최대 13byte*AES-256AES-256/ECB/PKCS5Padding + Hex
결제금액 (0원 결제 시 자동결제 키발급만 진행)
└productNmAN(95)영문+숫자, 최대 95byte*
상품명
└dutyFreeYnA(1)영문, 최대 1byte*
면세여부
Y: 면세 N: 과세 G: 복합과세
└callbackUrlAN(255)영문+숫자, 최대 255byte*
인증 완료 후 결제창에서 호출될 URL (https:// 권장)
*callbackUrl을 통해 응답받은 값을 검증 후 결제승인 API 호출. 도메인에 점(.)이 2개 이상인 주소를 사용해야 합니다. (예: www.example.com)
└cancelUrlAN(255)영문+숫자, 최대 255byte
결제 과정 중 사용자 취소 시 호출될 URL
*callbackUrl과 메인도메인이 같아야 함
└signatureAN(200)영문+숫자, 최대 200byte*SHA-256(실시간 생성)
SHA-256 방식으로 생성한 해쉬값
NOTE

해쉬 생성 조합

mercntId + ordNo + trDay + trTime + trPrice(평문) + callbackUrlHost + hashKey
NOTE

Signature 생성 시 callbackUrl HOST 추출 규칙 (apiVer 2.0)

  • 프로토콜(https://, http://)과 포트 번호를 제외한 도메인 주소만 사용합니다.
  • 예: https://develop.sbsvc.online:60001/callback/success → develop.sbsvc.online
  • 예: https://www.example.com/callback → www.example.com

선택 파라미터

└taxPriceAN(13)영문+숫자, 최대 13byteAES-256AES-256/ECB/PKCS5Padding + Hex
과세금액 (복합과세 시 필수)
└vatPriceAN(13)영문+숫자, 최대 13byteAES-256AES-256/ECB/PKCS5Padding + Hex
부가세금액 (과세금액의 10%)
└dutyFreePriceAN(13)영문+숫자, 최대 13byteAES-256AES-256/ECB/PKCS5Padding + Hex
면세금액 (복합과세 시 필수)
└containerDepositAN(5)영문+숫자, 최대 5byteAES-256AES-256/ECB/PKCS5Padding + Hex
자원순환보증금액 (현금영수증 비대상)
└criPsblYnA(1)영문, 최대 1byte
현금영수증 발행가능 여부
Y: 발행가능 N: 발행불가능
*빈값일 경우 Y로 인식
└addDeductionYnA(1)영문, 최대 1byte
추가공제구분
Y: 대중교통 C: 도서/공연비 N: 추가공제없음
└shopNmAN(10)영문+숫자, 최대 10byte
상점명
└cphoneNoAN(11)영문+숫자, 최대 11byteAES-256AES-256/ECB/PKCS5Padding + Hex
주문자 휴대폰번호 (하이픈 제외)
└emailAN(30)영문+숫자, 최대 30byteAES-256AES-256/ECB/PKCS5Padding + Hex
주문자 이메일
└regularpayYnA(1)영문, 최대 1byte
자동결제 등록 여부
Y: 자동결제 등록 N: 일반결제
*0원 인증: regularpayYn=Y, trPrice=0 / 자동결제: regularpayYn=Y, trPrice=금액
└mercntParam1AN(1000)영문+숫자, 최대 1000byte
가맹점 데이터 1 (응답 및 거래내역 조회 시 리턴)
└mercntParam2AN(1000)영문+숫자, 최대 1000byte
가맹점 데이터 2 (응답 및 거래내역 조회 시 리턴)
└payLimitCdAN(10)영문+숫자, 최대 10byte
결제 한도 코드 (내통장결제 정책에 따른 고객 결제한도 확인)

응답 파라미터 (Callback)

인증 완료 후 callbackUrl로 전달되는 파라미터입니다.

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└resultCdN(1)숫자, 최대 1byte*0
결과코드
0: 성공 -1: 실패
└errCdAN(5)영문+숫자, 최대 5byte*0000
실패코드 (실패코드 테이블 참조)
└resultMsgAN(200)영문+숫자, 최대 200byte*정상처리
결과 메시지
└mercntIdAN(8)영문+숫자, 최대 8byte*ms00003t
헥토파이낸셜에서 부여하는 고유 상점아이디
└ordNoAN(100)영문+숫자, 최대 100byte*OID201902210001
가맹점에서 요청한 주문번호
└authNoAN(20)영문+숫자, 최대 20byte*PAR20190220000000001
인증번호 (결제승인 API 호출 시 사용)
*결제승인 API 요청 시 필수
└trPriceN(13)숫자, 최대 13byte*15000
거래금액 (최초 결제 요청 금액)
└discntPriceN(13)숫자, 최대 13byte*1000
할인금액 (프로모션 선할인 등)
└payPriceN(13)숫자, 최대 13byte*14000
결제금액 (최종 출금 금액)
└trDayN(8)숫자, 최대 8byte*20190221
거래일자 (yyyyMMdd)
└trTimeN(6)숫자, 최대 6byte*142120
거래시간 (HH24MISS)
└mercntParam1AN(1000)영문+숫자, 최대 1000byte
요청 시 전달한 가맹점 데이터 1
└mercntParam2AN(1000)영문+숫자, 최대 1000byte
요청 시 전달한 가맹점 데이터 2

연동 예시

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>내통장결제</title>
</head>
<body>
    <form id="payForm" name="payForm">
        <input type="hidden" name="hdInfo" value="IA_AUTHPAGE_1.0_1.0" />
        <input type="hidden" name="apiVer" value="2.0" />
        <input type="hidden" name="processType" value="D" />
        <input type="hidden" name="mercntId" value="ms00003t" />
        <input type="hidden" name="ordNo" value="OID201902210001" />
        <input type="hidden" name="trDay" value="20190221" />
        <input type="hidden" name="trTime" value="142120" />
        <input type="hidden" name="trPrice" value="AES암호화된금액" />
        <input type="hidden" name="productNm" value="배추" />
        <input type="hidden" name="dutyFreeYn" value="N" />
        <input type="hidden" name="callbackUrl" value="https://www.example.com/callback" />
        <input type="hidden" name="cancelUrl" value="https://www.example.com/cancel" />
        <input type="hidden" name="signature" value="SHA256해쉬값" />
    </form>

    <!-- SDK 스크립트 로드 -->
    <script src="https://tbezauth.settlebank.co.kr/js/SettlePay.js" charset="UTF-8"></script>
    <script>
        // 결제창 호출
        SettlePay.execute(document.getElementById('payForm'));
    </script>
</body>
</html>
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?