헥토파이낸셜 개발자센터

화이트라벨 결제창 (UI)

화이트라벨 표준결제창을 호출하여 고객 인증을 진행합니다. 인증 완료 후 결제 API를 호출하여 실제 결제를 진행합니다.

테스트용 키 정보

주의 사항

trdNo 보관 필수

결제창 응답의 trdNo(거래번호)는 결제 API 호출 시 반드시 필요합니다. 안전하게 보관하세요.

지원 브라우저

크롬(Chrome), 엣지(Edge) 브라우저만 지원합니다. 이 외 브라우저에서는 정상적으로 동작하지 않을 수 있습니다.

운영환경 테스트 비용

운영환경에서 테스트 진행 시 발생하는 비용은 가맹점 부담입니다. 반드시 테스트 환경에서 먼저 테스트하세요.
  • 발행금액 파라미터 처리 기준 참고해 주세요.
    • 예) 과세 가맹점에서 거래금액 1,000원을 다음과 같이 전송하는 경우
      • 거래금액만 전송: 과세 901, 부가세 99로 처리
      • 과세금액 900, 부가세금액 100 전송: 과세 900, 부가세 100으로 처리
  • Iframe 사용 금지: 결제창 연동 시 Iframe을 사용하면 일부 브라우저나 기기에서 정상적으로 동작하지 않습니다.
  • 특수문자 사용 제한: 파라미터 값에 특수문자(:, &, ?, ', 개행, <, >) 및 이모지를 사용하지 마세요.
  • HTTPS 필수: nextUrl, cancUrl은 반드시 HTTPS를 사용해야 합니다. HTTP 사용 시 브라우저 정책 위반으로 결제창이 정상 동작하지 않을 수 있습니다.

API 정보

POST/whitelabel/main.do
Content-Typeapplication/x-www-form-urlencoded
테스트https://tbwl.settlebank.co.kr/whitelabel/main.do
운영https://wl.settlebank.co.kr/whitelabel/main.do

요청 파라미터

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

필수 파라미터

└mchtIdAN(10)영문+숫자, 최대 10byte*
헥토파이낸셜에서 부여하는 고유 상점아이디
└methodAN(20)영문+숫자, 최대 20byte*
화이트라벨 결제 구분 코드
*고정값
└trdDtN(8)숫자, 최대 8byte*
요청일자 (yyyyMMdd)
└trdTmN(6)숫자, 최대 6byte*
요청시간 (HH24MISS)
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*
상점에서 생성하는 고유 주문번호 (한글 제외)
└pmtPrdtNmAHN(300)영문+한글+숫자, 최대 300byte*
결제상품명
└trdAmtAN(12)영문+숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding + Base64
거래금액
└nextUrlAN(250)영문+숫자, 최대 250byte*
결제 후 결과 전달 및 이동페이지 URL
└cancUrlAN(250)영문+숫자, 최대 250byte*
고객 강제 종료시 결과 전달 및 이동페이지 URL
└mchtCustIdAN(100)영문+숫자, 최대 100byte*AES-256AES-256/ECB/PKCS5Padding + Base64
상점에서 보내주는 고유 고객아이디 혹은 유니크키
└pktHashAN(200)영문+숫자, 최대 200byte*SHA-256(실시간 생성)
SHA256 방식으로 생성한 해쉬값
*상점아이디 + 결제수단 + 상점주문번호 + 요청일자 + 요청시간 + 거래금액(평문) + 해쉬키

선택 파라미터

└mchtParamAHN(4000)영문+한글+숫자, 최대 4000byte
기타 주문 정보를 입력하는 상점 예약 필드
└emailAN(60)영문+숫자, 최대 60byteAES-256AES-256/ECB/PKCS5Padding + Base64
이메일 주소
└taxTypeCdA(1)영문, 최대 1byte
면세여부. 공백일 경우 상점 설정에 따름
N: 과세 Y: 면세 G: 복합과세
└taxAmtAN(12)영문+숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
과세금액 (복합과세일 경우 필수)
└vatAmtAN(12)영문+숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
부가세금액 (복합과세일 경우 필수)
└taxFreeAmtAN(12)영문+숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
비과세금액 (복합과세일 경우 필수)
└svcAmtAN(12)영문+숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
신용카드 봉사료
└themeColorCdAN(10)영문+숫자, 최대 10byte
테마컬러 (헥스 코드)
└custAcntSumryAHN(30)영문+한글+숫자, 최대 30byte
고객의 통장에 찍히는 인자명 (고객계좌적요)
└cupDepositAmtN(12)숫자, 최대 12byte
자원순환보증금 (컵보증금)
└addDdtTypeCdA(1)영문, 최대 1byte
현금영수증 추가공제구분
Y: 대중교통 C: 도서,공연비
└ciChkYnA(1)영문, 최대 1byte
고객아이디 CI 검증 여부. 사용(Y)시 고객아이디에 CI 입력
Y: 사용 (mchtCustId에 CI 입력) N: 미사용

응답 파라미터

화이트라벨 결제창에서 가맹점측으로 응답하는 파라미터입니다. 결제창 인증 완료 후 nextUrl로 POST 전달됩니다.

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└mchtIdAN(10)영문+숫자, 최대 10byte*pg_test
헥토파이낸셜에서 부여하는 고유 상점아이디
└outStatCdAN(4)영문+숫자, 최대 4byte*0021
거래상태코드 (성공/실패)
0021: 성공 0031: 실패
└outRsltCdAN(4)영문+숫자, 최대 4byte*0000
거절코드. 거래상태가 '0031'일 경우, 상세 코드 전달
*거절 코드 표 참고
└outRsltMsgAHN(200)영문+한글+숫자, 최대 200byte*성공
결과메세지 (URL Encoding, UTF-8)
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*ORDER20260107143000
상점에서 생성하는 고유 주문번호 (한글 제외)
└mchtCustIdAN(100)영문+숫자, 최대 100byteAES-256AES-256/ECB/PKCS5PaddingHongGilDong
상점에서 보내주는 고유 고객아이디 혹은 유니크키
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└trdNoAN(40)영문+숫자, 최대 40byte*STFP_PGCApg_test0000260107143000M1717578
헥토파이낸셜 거래번호. 결제 API 호출 시 필수
└trdAmtAN(12)영문+숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding1000
거래금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└mchtParamAHN(4000)영문+한글+숫자, 최대 4000bytename=HongGilDong&age=25
요청으로 받은 필드값을 응답으로 Bypass

연동 예시

<form id="paymentForm" method="POST" action="https://tbwl.settlebank.co.kr/whitelabel/main.do">
    <input type="hidden" name="mchtId" value="pg_test" />
    <input type="hidden" name="method" value="whitelabel" />
    <input type="hidden" name="trdDt" value="20260107" />
    <input type="hidden" name="trdTm" value="143000" />
    <input type="hidden" name="mchtTrdNo" value="ORDER20260107143000" />
    <input type="hidden" name="pmtPrdtNm" value="테스트상품" />
    <input type="hidden" name="trdAmt" value="vqIWIiimsJ5efjSJpfnnTw==" />
    <input type="hidden" name="nextUrl" value="https://example.com/payment/result" />
    <input type="hidden" name="cancUrl" value="https://example.com/payment/cancel" />
    <input type="hidden" name="mchtCustId" value="암호화된고객ID" />
    <input type="hidden" name="pktHash" value="해시값" />
</form>

<script>
document.getElementById('paymentForm').submit();
</script>

다음 단계

결제창 인증 완료 후, 결제 API를 호출하여 실제 결제를 진행합니다.

결제 API 연동

💳

결제 API

결제 승인 (Non-UI)

❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?