전체 연동 플로우
내통장결제는 결제창(UI) 인증 → Callback 수신 → 결제승인(API) 3단계로 구성됩니다.
전체 흐름
고객
가맹점 프론트
가맹점 서버
헥토파이낸셜
11. 결제 요청
1. 결제 요청
22. 결제창 호출 (SettlePay.execute)
2. 결제창 호출 (SettlePay.execute)
33. 결제창 표시
3. 결제창 표시
44. 본인인증 및 계좌 등록
4. 본인인증 및 계좌 등록
55. 인증 결과 전달 (callbackUrl)
5. 인증 결과 전달 (callbackUrl)
66. 결제승인 API 호출
6. 결제승인 API 호출
77. 결제 결과 응답
7. 결제 결과 응답
88. 결제 완료 처리
8. 결제 완료 처리
1단계: 결제창 호출 (UI)
가맹점 프론트엔드에서 헥토파이낸셜이 제공하는 SettlePay.js 스크립트를 로드하고 결제창을 호출합니다.
<!-- SDK 스크립트 로드 (테스트베드) -->
<script src="https://tbezauth.settlebank.co.kr/js/SettlePay.js" charset="UTF-8"></script>
<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="상점 ID" />
<input type="hidden" name="ordNo" value="주문번호" />
<input type="hidden" name="trDay" value="거래일자(yyyyMMdd)" />
<input type="hidden" name="trTime" value="거래시각(HH24MISS)" />
<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="signature" value="SHA256 해쉬값" />
</form>
<script>
SettlePay.execute(document.getElementById('payForm'));
</script>
NOTE
callbackUrl 도메인 조건
callbackUrl은 도메인에 점(.)이 2개 이상인 주소를 사용해야 합니다. (예: www.example.com)
signature 생성 규칙
| 조합 순서 | 필드 |
|---|---|
| 1 | mercntId |
| 2 | ordNo |
| 3 | trDay |
| 4 | trTime |
| 5 | trPrice (평문) |
| 6 | callbackUrl의 HOST (프로토콜·포트 제외) |
| 7 | hashKey |
signature 생성 시 주의
trPrice는 암호화 전 평문 값을 사용합니다. callbackUrl HOST는 프로토콜(https://)과 포트 번호를 제외한 도메인만 사용합니다. 예: https://www.example.com/callback → www.example.com
2단계: 인증 결과 수신 (Callback)
결제창에서 인증이 완료되면 callbackUrl로 결과가 전달됩니다. 가맹점 서버는 이 결과를 받아 정합성을 확인합니다.
주요 응답 파라미터
| 필드 | 설명 |
|---|---|
resultCd | 결과코드 (0: 성공, -1: 실패) |
authNo | 인증번호 (결제승인 API 호출 시 필수) |
trPrice | 거래금액 |
payPrice | 최종 결제금액 |
정합성 확인 필수
callbackUrl로 수신한 값은 반드시 검증한 후 결제승인 API를 호출해야 합니다. 수신 금액과 주문 금액이 일치하는지 확인하세요.
3단계: 결제승인 API 호출
가맹점 서버에서 인증 결과를 확인한 후, 결제승인 API를 호출하여 실제 출금이체를 실행합니다.
| 항목 | 값 |
|---|---|
| 테스트베드 | https://tbezauthapi.settlebank.co.kr |
| 상용 환경 | https://ezauthapi.settlebank.co.kr:8081 |
| URI | /v3/APIPayApprov.do |
| Method | POST |
타임아웃 처리
결제승인 API에서 타임아웃(35초)이 발생한 경우, 아래 순서로 처리합니다.
- 거래결과조회 API 호출 → 결제 상태 확인
- 결제 성공 상태 확인 시 → 망취소 API 호출하여 취소 처리
조회/망취소 API 문서
파라미터 검증 실패 응답
요청 파라미터 검증 실패 시 다음과 같은 응답이 반환됩니다.
{
"resultCd": "-1",
"errCd": "ST09",
"resultMsg": "유효하지 않는 요청전문"
}
