헥토파이낸셜 개발자센터

가상계좌 채번 (고정식 무제한) API

고정식 무제한(acntType=3) 방식은 한 번 채번한 가상계좌번호를 계속 재사용하여 반복 입금을 받을 수 있는 방식입니다. 매 거래마다 새 번호를 발급하는 회전식과 달리, 미리 할당된 계좌번호를 고객 전용으로 사용합니다.

테스트용 키 정보

주의 사항

사전 협의 필수

고정식 무제한 방식은 헥토파이낸셜과 사전 협의가 완료된 가맹점만 사용할 수 있습니다. 상점아이디와 가상계좌번호 리스트를 별도로 발급받아야 합니다.
NOTE

현금영수증 별도 호출 필요

고정식 무제한 방식의 경우, 현금영수증 API를 따로 호출해야 합니다. 현금영수증 발급 API 보기

노티 관련 주의사항

채번 시 채번 완료 노티(outStatCd: 0051)는 발송되지 않으며, 채번 성공 여부는 API 응답으로만 확인합니다. 입금 완료 노티(bizType: B1)는 정상 발송되나, 노티 URL은 영업 담당자를 통해 요청하여 상점 기준정보에 등록해야 합니다.
  • 거래금액(trdAmt)은 항상 0으로 설정합니다.
  • vAcntNo(가상계좌번호)는 미리 발급된 목록에서 선택하여 사용합니다.
  • 입금 만료일(expireDate)은 무제한으로 설정할 수 있습니다. 단, 채번 취소는 채번일 기준 1년 이내에만 가능합니다.
  • 가상계좌 은행코드는 가상계좌 은행 코드 목록 참고 바랍니다.

API 정보

POST/spay/APIVBank.do
Content-Typeapplication/json
테스트https://tbgw.settlebank.co.kr/spay/APIVBank.do
운영https://gw.settlebank.co.kr/spay/APIVBank.do

요청 파라미터

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

params 객체

└mchtIdAN(10)영문+숫자, 최대 10byte*
헥토파이낸셜에서 부여하는 고유 상점아이디
nxva_fix2: 고정식 무제한 전용
└verAN(4)영문+숫자, 최대 4byte*
전문의 버전
*고정값
└methodA(2)영문, 최대 2byte*
결제수단
*고정값 (가상계좌)
└bizTypeAN(2)영문+숫자, 최대 2byte*
업무 구분코드
*고정값 (채번)
└encCdN(2)숫자, 최대 2byte*
암호화 구분 코드
*고정값
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*
상점에서 생성하는 고유한 주문번호
└trdDtN(8)숫자, 최대 8byte*
현재 전문을 전송하는 일자 (YYYYMMDD)
└trdTmN(6)숫자, 최대 6byte*
현재 전문을 전송하는 시간 (HHMMSS)
└mobileYnA(1)영문, 최대 1byte
모바일 여부
Y: 모바일웹/앱 N: PC 또는 그 외
└osTypeA(1)영문, 최대 1byte
OS 구분
A: Android I: IOS W: Windows M: Mac E: 기타

data 객체

└pktHashAN(200)영문+숫자, 최대 200byte*SHA-256(실시간 생성)
SHA256 방식으로 생성한 해쉬값
NOTE

해쉬 생성 조합

trdDt + trdTm + mchtId + mchtTrdNo + trdAmt(평문) + hashKey
└bankCdAN(3)영문+숫자, 최대 3byte*
가상계좌 은행코드
*가상계좌 은행 코드 목록 참고. 테스트 환경에서는 004(국민은행), 011(농협은행)만 사용 가능
└acntTypeN(1)숫자, 최대 1byte*
계좌구분
3: 고정식 무제한 (계좌 미리 할당받아 반복 사용)
└vAcntNoN(16)숫자, 최대 16byte*AES-256AES-256/ECB/PKCS5Padding + Base64
가상계좌번호 (고정식 무제한 전용)
*미리 발급받은 고정식 가상계좌번호를 AES 암호화하여 전송. 테스트 환경의 가상계좌 리스트 참고
└expireDateN(14)숫자, 최대 14byte
입금만료일시 (YYYYMMDDhhmmss)
*미설정시 거래일 기준 10일 뒤로 자동 설정. 무제한 설정 가능하나 채번 취소는 채번일 기준 1년 이내에만 가능
└prdtNmAHN(128)영문+한글+숫자, 최대 128byte*
상품명
└sellerNmAHN(128)영문+한글+숫자, 최대 128byte*
판매자명
└ordNmAHN(30)영문+한글+숫자, 최대 30byte
주문자명
└trdAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding + Base64
거래금액
*고정식 무제한(acntType=3)은 반드시 0으로 설정
└dpstrNmAHN(50)영문+한글+숫자, 최대 50byte
통장인자명
*공백일 경우 sellerNm(판매자명)을 통장인자명으로 사용
└mchtCustIdAN(50)영문+숫자, 최대 50byte
상점에서 보내주는 고유 고객아이디 혹은 유니크키

테스트 환경 고정식 무제한 가상계좌 리스트

테스트 환경(tbgw.settlebank.co.kr)에서만 사용할 수 있는 고정식 무제한 가상계좌번호입니다.

상점아이디(mchtId)은행코드(bankCd)가상계좌번호(vAcntNo)
nxva_fix2004 (국민은행)2022004000056 ~ 2022004000100
nxva_fix2011 (농협은행)2022011000056 ~ 2022011000100

응답 파라미터

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

params 객체

└mchtIdAN(10)영문+숫자, 최대 10byte*nx_mid_il
헥토파이낸셜에서 부여하는 고유 상점아이디
└verAN(4)영문+숫자, 최대 4byte*0A19
전문의 버전
*고정값
└methodA(2)영문, 최대 2byte*VA
결제수단
*고정값
└bizTypeAN(2)영문+숫자, 최대 2byte*A0
업무 구분코드
*고정값 (채번)
└encCdN(2)숫자, 최대 2byte*23
암호화 구분 코드
*고정값
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*ORDER20211231100000
상점에서 생성하는 고유한 거래번호
└trdNoAN(40)영문+숫자, 최대 40byte*STFP_PGVAnx_mid_il00210806075210M1853381
헥토파이낸셜에서 생성하는 고유한 거래번호
└trdDtN(8)숫자, 최대 8byte*20211231
요청일자 (YYYYMMDD)
└trdTmN(6)숫자, 최대 6byte*100000
요청시간 (HHMMSS)
└outStatCdAN(4)영문+숫자, 최대 4byte*0021
거래상태코드 (성공/실패)
0021: 채번 성공 0031: 실패
└outRsltCdAN(4)영문+숫자, 최대 4byte*0000
거절코드. 거래상태가 '0031'일 경우 상세 코드 전달
└outRsltMsgAHN(200)영문+한글+숫자, 최대 200byte*정상적으로 처리되었습니다.
결과 메세지 전달 (URL Encoding, UTF-8)

data 객체

└pktHashAN(64)영문+숫자, 최대 64byte*
요청시 hash 값 그대로 return
└bankCdAN(3)영문+숫자, 최대 3byte*011
가상계좌 은행코드
└vAcntNoN(16)숫자, 최대 16byte*AES-256AES-256/ECB/PKCS5Padding0123456789
채번받은 가상계좌번호
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└expireDateN(14)숫자, 최대 14byte*20271231235959
입금만료일시 (YYYYMMDDhhmmss)
└trdAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding0
거래금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└acntTypeN(1)숫자, 최대 1byte*3
계좌구분 (요청시 값 그대로 전달)
3: 고정식 무제한
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?