헥토파이낸셜 개발자센터

가상계좌 결제 (결제창 방식)

결제창 방식은 고객이 결제 화면에서 직접 가상계좌를 발급받아 입금하는 방식입니다.

테스트용 키 정보

API 정보

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

주의 사항

가상계좌 입금 안내

가상계좌는 발급 후 만료일까지 유효하며, 입금금액이 설정된 금액과 정확히 일치해야 자동 승인됩니다.
  • 가상계좌번호는 고유하며, 중복 발급되지 않습니다.
  • 만료일 이후에는 입금이 불가능합니다.
  • 입금 완료 시 노티(notiUrl)를 통해 결과를 받을 수 있습니다.

요청 파라미터

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

필수 파라미터

└mchtIdAN(10)영문+숫자, 최대 10byte*
헥토파이낸셜에서 부여하는 고유 상점아이디
nx_mid_il: 가상계좌
└methodAN(20)영문+숫자, 최대 20byte*
PG 서비스에 해당하는 결제 구분 코드
*고정값
└trdDtN(8)숫자, 최대 8byte*
요청일자 (yyyyMMdd)
└trdTmN(6)숫자, 최대 6byte*
요청시간 (HH24MISS)
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*
상점에서 생성하는 고유 주문번호 (한글 제외)
└mchtNameAHN(100)영문+한글+숫자, 최대 100byte*
상점한글명
└mchtENameAN(100)영문+숫자, 최대 100byte*
상점영문명
└pmtPrdtNmAHN(128)영문+한글+숫자, 최대 128byte*
결제상품명
└trdAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding + Base64
거래금액
└notiUrlAN(250)영문+숫자, 최대 250byte*
입금 완료 후 결과 전달되는 페이지의 URL (Server To Server 연동 URL)
└nextUrlAN(250)영문+숫자, 최대 250byte*
가상계좌 발급 후 결과 화면으로 전환되는 URL
*결제창 내 버튼 클릭 시 리다이렉트 됩니다. outStatCd 값으로 채번 성공(0051)/실패(0031) 여부를 확인하세요.
└cancUrlAN(250)영문+숫자, 최대 250byte*
고객이 결제창의 X 버튼 클릭 시 리다이렉트 되는 URL
*브라우저 종료, 뒤로가기 등은 감지되지 않습니다.
└pktHashAN(200)영문+숫자, 최대 200byte*SHA-256(실시간 생성)
SHA256 방식으로 생성한 해쉬값
NOTE

해쉬 생성 조합

mchtId + method + mchtTrdNo + trdDt + trdTm + trdAmt(평문) + hashKey

선택 파라미터

└mchtCustNmAHN(30)영문+한글+숫자, 최대 30byteAES-256AES-256/ECB/PKCS5Padding + Base64
고객명
└mchtParamAHN(4000)영문+한글+숫자, 최대 4000byte
기타 주문 정보를 입력하는 상점 예약 필드
└emailAN(60)영문+숫자, 최대 60byteAES-256AES-256/ECB/PKCS5Padding + Base64
이메일 주소
└prdtTermN(14)숫자, 최대 14byte
상품제공기간 (yyyyMMddHHmmss). 값이 없으면 일반결제로 표기
└mchtCustIdAN(50)영문+숫자, 최대 50byteAES-256AES-256/ECB/PKCS5Padding + Base64
상점에서 보내주는 고유 고객아이디 혹은 유니크키
└custAcntSumryAHN(50)영문+한글+숫자, 최대 50byte
통장인자내용. 고객의 통장에 찍힐 인자명. 공백일 경우 상점한글명을 사용
└expireDtN(14)숫자, 최대 14byte
입금만료일시 (yyyyMMddHHmmss)
*미설정시 거래일 기준 10일 뒤로 자동 설정. 최대 현재일 기준 +365일(1년)까지 설정 가능
└cphoneNoN(11)숫자, 최대 11byteAES-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주소

응답 파라미터

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

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└mchtIdAN(10)영문+숫자, 최대 10byte*nx_mid_il
헥토파이낸셜에서 부여하는 고유 상점아이디
└outStatCdAN(4)영문+숫자, 최대 4byte*0051
거래상태코드 (성공/실패)
0051: 채번 성공(입금대기중) 0031: 실패
└outRsltCdAN(4)영문+숫자, 최대 4byte*0000
거절코드. 거래상태가 '0031'일 경우, 상세 코드 전달
*거절 코드 표 참고
└outRsltMsgAHN(200)영문+한글+숫자, 최대 200byte*정상적으로 처리되었습니다.
결과메세지 (URL Encoding, UTF-8)
└methodAN(20)영문+숫자, 최대 20byte*vbank
PG 서비스에 해당하는 결제 구분 코드
*고정값
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*ORDER20211231100000
상점에서 생성하는 고유 주문번호
└trdNoAN(40)영문+숫자, 최대 40byte*STFP_PGVBnxvb_jt_il0211129135810M1494620
헥토파이낸셜 거래번호
└trdAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding1000
거래금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└vtlAcntNoN(30)숫자, 최대 30byteAES-256AES-256/ECB/PKCS5Padding1234567890123456
발급된 가상계좌번호
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└fnNmAH(50)영문+한글, 최대 50byte국민은행
가상계좌 은행명
└fnCdN(4)숫자, 최대 4byte004
가상계좌 은행코드
└expireDtN(14)숫자, 최대 14byte20271231235959
가상계좌 입금기한 (yyyyMMddHHmmss)
└mchtCustIdAN(50)영문+숫자, 최대 50byteAES-256AES-256/ECB/PKCS5PaddingHongGilDong
상점고객아이디
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└authDtN(14)숫자, 최대 14byte20211231100000
승인일시 (가상계좌 주문/채번 일시)
└reqIssueDtN(14)숫자, 최대 14byte20211231100000
채번요청일시 (010가상계좌인 경우)
└mchtParamAHN(4000)영문+한글+숫자, 최대 4000bytename=HongGilDong&age=25
요청으로 받은 필드값을 응답으로 Bypass

노티 전문 (결과통보)

가상계좌는 채번노티와 입금노티 2번의 노티가 전송됩니다.

2단계 노티 처리 필수

가상계좌는 계좌 발급 시(채번노티)와 실제 입금 완료 시(입금노티) 각각 노티가 전송됩니다. 반드시 두 노티를 모두 처리해야 합니다. 노티 전문 문서 보기
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?