헥토파이낸셜 개발자센터

010가상계좌 결제창 호출

헥토파이낸셜에서 제공하는 010 가상계좌 결제창(UI)을 호출하여 가상계좌를 발급받는 방식입니다. 결제창 내에서 휴대폰 점유인증, 인증확인, 채번이 자동으로 처리됩니다.

테스트용 키 정보

API 정보

POST/vbank010/main.do
Content-Typeapplication/x-www-form-urlencoded
테스트https://tbnpg.settlebank.co.kr/vbank010/main.do
운영https://npg.settlebank.co.kr/vbank010/main.do

주의 사항

URL 처리 필수

nextUrl은 결제 결과 화면 표시용이고, notiUrl은 가맹점 서버 DB 처리용입니다. 결제창 강제 종료 시 nextUrl은 호출되지 않으므로 DB 처리는 반드시 notiUrl에서 해야 합니다.

결제창에서는 점유인증 생략 불가

결제창(UI) 방식은 항상 화면 내에서 휴대폰 점유인증(SMS 발송 → 인증번호 입력)을 진행합니다. cphoneNo와 mchtCustId를 전달하더라도 점유인증 단계를 건너뛸 수 없습니다. 점유인증 생략은 API 방식에서만 가능합니다.
  • 운영환경에서 테스트 진행 시 발생하는 비용은 가맹점 부담입니다.
  • nextUrl, notiUrl, cancUrl은 HTTPS 사용을 권장합니다.
  • 요청 파라미터에 :, &, ?, ', ", <, > 등의 특수문자 사용을 삼가 주세요.
  • 요청 파라미터에 href, alert, javascript, console.log 등의 예약어가 포함될 경우 자동으로 제거됩니다.

결제창 유형

유형method 값URL설명
단독창vbank010/vbank010/main.do010 가상계좌 전용 결제창
통합결제창vbank/vbank/main.do일반 가상계좌와 통합된 결제창

요청 파라미터

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└mchtIdAN(10)영문+숫자, 최대 10byte*
헥토파이낸셜에서 부여하는 고유 상점아이디
└methodAN(12)영문+숫자, 최대 12byte*
결제수단 코드
vbank: 통합결제창 vbank010: 단독창
└trdDtN(8)숫자, 최대 8byte*
요청일자 (yyyyMMdd)
└trdTmN(6)숫자, 최대 6byte*
요청시간 (HHmmss)
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*
상점에서 생성하는 고유 주문번호 (한글 제외)
└mchtNameAHN(100)영문+한글+숫자, 최대 100byte*
상점 한글명
└mchtENameAN(100)영문+숫자, 최대 100byte*
상점 영문명
└pmtPrdtNmAHN(50)영문+한글+숫자, 최대 50byte*
결제 상품명
└trdAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding + Base64
거래금액
└mchtCustNmAHN(30)영문+한글+숫자, 최대 30byteAES-256AES-256/ECB/PKCS5Padding + Base64
고객명
└custAcntSumryAHN(50)영문+한글+숫자, 최대 50byte
통장인자내용 (고객의 통장에 찍힐 인자명)
*공백일 경우 상점한글명을 통장인자명으로 사용
└expireDtN(14)숫자, 최대 14byte*
입금만료일시 (yyyyMMddHHmmss)
*공백 시 거래일 기준 +10일. B2C: 최대 27일, B2B: 최대 3년
└notiUrlAN(250)영문+숫자, 최대 250byte*
결과처리 URL (Server To Server 연동 URL)
*결제 완료 시 가맹점 서버로 결과 전송. DB 처리는 여기서!
└nextUrlAN(250)영문+숫자, 최대 250byte*
결과화면 URL (결제 후 이동 페이지)
*결제창 닫기 버튼 클릭 시 호출. 강제 종료 시 호출 안됨
└cancUrlAN(250)영문+숫자, 최대 250byte*
결제취소 URL (취소/실패 시 이동 페이지)
└mchtParamAHN(4000)영문+한글+숫자, 최대 4000byte
상점 예약 필드 (응답 시 ByPass)
└emailAN(60)영문+숫자, 최대 60byteAES-256AES-256/ECB/PKCS5Padding + Base64
고객 이메일 주소
└prdtTermN(14)숫자, 최대 14byte
상품제공기간 (yyyyMMddHHmmss). 값이 없으면 일반결제로 표기
└cphoneNoN(11)숫자, 최대 11byteAES-256AES-256/ECB/PKCS5Padding + Base64
휴대폰번호 (하이픈 제거). 전달 시 결제창 내 휴대폰번호 입력란에 자동으로 채워집니다.
*결제창에서는 점유인증이 항상 진행됩니다. 이 값을 전달해도 인증 단계를 생략할 수 없습니다.
└mchtCustIdAN(50)영문+숫자, 최대 50byteAES-256AES-256/ECB/PKCS5Padding + Base64
상점 고객 아이디
└taxTypeCdA(1)영문, 최대 1byte
면세 여부
N: 과세 Y: 면세 G: 복합과세
*공백일 경우 상점 설정에 따름
└taxAmtN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
과세금액 (복합과세일 경우 필수)
└vatAmtN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
부가세금액 (복합과세일 경우 필수)
└taxFreeAmtN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
비과세금액 (복합과세일 경우 필수)
└custIpAN(15)영문+숫자, 최대 15byte
고객 IP 주소 (상점 서버 IP가 아닌 고객 기기 IP)
└pktHashAN(200)영문+숫자, 최대 200byte*SHA-256(실시간 생성)
SHA256 방식으로 생성한 해쉬값
*상점아이디 + 결제수단 + 상점주문번호 + 요청일자 + 요청시간 + 거래금액(평문) + 해쉬키

응답 파라미터

가상계좌 발급 완료 시 nextUrl로, 고객이 결제창 내 X 버튼을 클릭하면 cancUrl로 리다이렉트되며 아래 파라미터가 전달됩니다. 실제 입금 결과는 고객 입금 후 notiUrl(노티 전문)로 전달됩니다.

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└mchtIdAN(10)영문+숫자, 최대 10byte*nxva_sb_il
상점아이디
└outStatCdAN(4)영문+숫자, 최대 4byte*0051
거래상태코드
0051: 채번 성공 0031: 실패
└outRsltCdAN(4)영문+숫자, 최대 4byte*0000
거절코드 (0031일 경우 상세 코드)
└outRsltMsgAHN(200)영문+한글+숫자, 최대 200byte*정상적으로 처리되었습니다.
결과 메시지 (URL Encoding UTF-8)
└methodAN(12)영문+숫자, 최대 12byte*vbank010
결제수단
vbank: 통합결제창 vbank010: 단독창
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*ORDER20211231100000
상점주문번호
└mchtCustIdAN(50)영문+숫자, 최대 50byteAES-256AES-256/ECB/PKCS5PaddingHongGilDong
상점고객아이디
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└trdNoAN(40)영문+숫자, 최대 40byte*STBK_0123456789
헥토파이낸셜 거래번호
└trdAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding1000
거래금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└mchtParamAHN(4000)영문+한글+숫자, 최대 4000bytecustom_data
상점예약필드 (요청값 ByPass)
└authDtN(14)숫자, 최대 14byte20211231120000
승인일시 (yyyyMMddHHmmss)
└reqIssueDtN(14)숫자, 최대 14byte20211231120000
채번요청일시 (yyyyMMddHHmmss)
└vtlAcntNoN(30)숫자, 최대 30byteAES-256AES-256/ECB/PKCS5Padding01012345678
가상계좌번호
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└expireDtN(14)숫자, 최대 14byte20211231235959
입금만료일시 (yyyyMMddHHmmss)
└fnNmAH(50)영문+한글, 최대 50byteK뱅크
은행명
└fnCdN(4)숫자, 최대 4byte089
은행코드

요청 예시 (HTML Form)

<form id="payForm" method="POST" action="https://tbnpg.settlebank.co.kr/vbank010/main.do">
  <input type="hidden" name="mchtId" value="nxva_sb_il">
  <input type="hidden" name="method" value="vbank010">
  <input type="hidden" name="trdDt" value="20211231">
  <input type="hidden" name="trdTm" value="120000">
  <input type="hidden" name="mchtTrdNo" value="ORDER20211231100000">
  <input type="hidden" name="mchtName" value="헥토파이낸셜">
  <input type="hidden" name="mchtEName" value="Hecto Financial">
  <input type="hidden" name="pmtPrdtNm" value="테스트상품">
  <input type="hidden" name="trdAmt" value="AES암호화된금액">
  <input type="hidden" name="expireDt" value="20211231235959">
  <input type="hidden" name="notiUrl" value="https://example.com/noti">
  <input type="hidden" name="nextUrl" value="https://example.com/result">
  <input type="hidden" name="cancUrl" value="https://example.com/cancel">
  <input type="hidden" name="pktHash" value="해시값">
  <button type="submit">결제하기</button>
</form>

결제 흐름

[구매자, 가맹점, 결제창, 헥토파이낸셜]

구매자 -> 가맹점 : 결제 요청
가맹점 -> 결제창 : 결제창 호출 (Form POST)
결제창 -> 구매자 : 휴대폰 번호 입력 요청
구매자 -> 결제창 : 휴대폰 번호 입력
결제창 -> 헥토파이낸셜 : 점유인증 요청 (S1)
헥토파이낸셜 -> 구매자 : SMS 인증번호 발송
구매자 -> 결제창 : 인증번호 입력
결제창 -> 헥토파이낸셜 : 인증확인 (S2)
결제창 -> 헥토파이낸셜 : 채번 요청 (A4)
헥토파이낸셜 -> 결제창 : 010 가상계좌 발급
결제창 -> 가맹점 : nextUrl 호출 (응답 전달)
헥토파이낸셜 -> 가맹점 : notiUrl 호출 (채번 노티)
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?