헥토파이낸셜 개발자센터

010가상계좌 채번 API

휴대폰 점유인증 완료 후 010 가상계좌 번호를 발급받는 API입니다.

테스트용 키 정보

API 정보

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

주의 사항

채번 전 필수 확인

채번 API 호출 전 휴대폰 점유인증(S1, S2)이 완료되어야 합니다. 인증 요청시 사용한 mchtTrdNo와 동일한 값을 사용해야 합니다.
NOTE

점유인증 생략 채번

cphoneNo(휴대폰번호)와 mchtCustId(상점고객아이디)를 함께 전송하고, 동일한 cphoneNo + mchtCustId 조합으로 27일 이내 점유인증(S1/S2) 완료 이력이 있는 경우 S1/S2 단계를 생략하고 바로 채번을 요청할 수 있습니다. 두 조건 중 하나라도 충족되지 않으면 반드시 S1 → S2 → A4 순서로 진행해야 합니다.
  • 발급된 가상계좌는 K뱅크(089) 계좌입니다.
  • B2C: 통장인자명은 "010가상계좌"로 고정됩니다.
  • B2B: 통장인자명은 "010_고객명" 형식입니다.
  • B2B 이용 시 가상계좌번호는 휴대폰번호 + 3자리 형식입니다.

요청 파라미터

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

params 객체

└mchtIdAN(12)영문+숫자, 최대 12byte*
헥토파이낸셜에서 부여하는 고유 상점아이디
└verAN(4)영문+숫자, 최대 4byte*
전문 버전
└methodA(2)영문, 최대 2byte*
결제수단
└bizTypeAN(2)영문+숫자, 최대 2byte*
업무 구분코드
*A4: 010가상계좌 채번
└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(64)영문+숫자, 최대 64byte*SHA-256(실시간 생성)
SHA256 방식으로 생성한 해쉬값
*요청일자 + 요청시간 + 상점아이디 + 상점주문번호 + 거래금액(평문) + 해쉬키
└bankCdAN(3)영문+숫자, 최대 3byte*
가상계좌 은행코드
*K뱅크 고정
└vAcntNoN(14)숫자, 최대 14byte*AES-256AES-256/ECB/PKCS5Padding + Base64
채번받을 가상계좌번호 (휴대폰번호). B2B 이용시 휴대폰번호 뒤에 3자리 추가
└expireDateN(14)숫자, 최대 14byte*
입금만료일시 (yyyyMMddHHmmss)
*B2C: 현재일+최대27일, B2B: 현재일+최대3년. 공백시 +10일 자동설정
└prdtNmAHN(128)영문+한글+숫자, 최대 128byte*
상품명
└sellerNmAHN(128)영문+한글+숫자, 최대 128byte
판매자명
└ordNmAHN(30)영문+한글+숫자, 최대 30byte*
주문자명
└trdAmtN(9)숫자, 최대 9byte*AES-256AES-256/ECB/PKCS5Padding + Base64
거래금액
*B2C: 실제 거래가격, B2B: 1원 이상 (실제 입금통보 금액과 무관)
└dpstrNmAHN(50)영문+한글+숫자, 최대 50byte
예금주명
*B2C: 사용안함(고정값), B2B: 점유인증 응답값 필수 전송
└taxTypeCdA(1)영문, 최대 1byte*
면세여부. 공백시 상점 설정에 따름
N: 과세 Y: 면세 G: 복합과세
└taxAmtN(9)숫자, 최대 9byteAES-256AES-256/ECB/PKCS5Padding + Base64
과세금액 (복합과세일 경우 필수)
└vatAmtN(9)숫자, 최대 9byteAES-256AES-256/ECB/PKCS5Padding + Base64
부가세금액 (복합과세일 경우 필수)
└taxFreeAmtN(9)숫자, 최대 9byteAES-256AES-256/ECB/PKCS5Padding + Base64
비과세금액 (복합과세일 경우 필수)
└escrAgrYnA(1)영문, 최대 1byte*
에스크로 사용여부
Y: 동의 N: 비동의
└escrPwdAN(64)영문+숫자, 최대 64byteAES-256AES-256/ECB/PKCS5Padding + Base64
에스크로 비밀번호 (에스크로 사용시 필수)
└rfdDpstrNmAHN(50)영문+한글+숫자, 최대 50byteAES-256AES-256/ECB/PKCS5Padding + Base64
에스크로 환불시 예금주명 (에스크로 사용시 필수)
└csrcIssReqYnA(1)영문, 최대 1byte*
현금영수증 발행여부
Y: 발행 N: 미발행
└cashRcptPrposDivCdN(1)숫자, 최대 1byte
현금영수증 용도구분 (현금영수증 사용시 필수)
0: 소득증빙용 1: 지출증빙용
└csrcRegNoDivCdN(1)숫자, 최대 1byte
현금영수증 등록번호구분코드 (현금영수증 사용시 필수)
1: 카드 2: 주민번호 3: 사업자번호 4: 휴대폰번호
└csrcRegNoAN(64)영문+숫자, 최대 64byteAES-256AES-256/ECB/PKCS5Padding + Base64
현금영수증 고유식별정보 (현금영수증 사용시 필수)
└emailAN(60)영문+숫자, 최대 60byte
사용자 이메일 (에스크로 사용시 필수)
└notiUrlAN(250)영문+숫자, 최대 250byte*
결제 후 결과 전달되는 페이지의 URL (Server To Server 연동 URL)
└mchtParamAHN(4000)영문+한글+숫자, 최대 4000byte
상점 예약 필드 (요청값 그대로 응답으로 Bypass)
└mchtCustIdAN(50)영문+숫자, 최대 50byte*
상점 고객 아이디

응답 파라미터

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

params 객체

└mchtIdAN(10)영문+숫자, 최대 10byte*nxva_sb_il
상점아이디
└verAN(4)영문+숫자, 최대 4byte*0A18
전문 버전
└methodA(2)영문, 최대 2byte*VA
결제수단
└bizTypeAN(2)영문+숫자, 최대 2byte*A4
업무 구분코드
└encCdN(2)숫자, 최대 2byte*23
암호화 구분 코드
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*ORDER20211231100000
상점주문번호
└trdNoAN(40)영문+숫자, 최대 40byte*STBK_0123456789
헥토파이낸셜 거래번호
└trdDtN(8)숫자, 최대 8byte*20211231
요청일자
└trdTmN(6)숫자, 최대 6byte*120000
요청시간
└outStatCdAN(4)영문+숫자, 최대 4byte*0021
거래상태코드
0021: 성공 0031: 실패
└outRsltCdAN(4)영문+숫자, 최대 4byte*0000
결과코드 (0000인 경우 정상)
*VA03: B2B 이용시 이미 발급된 가상계좌번호 존재
└outRsltMsgAHN(200)영문+한글+숫자, 최대 200byte*정상적으로 처리되었습니다.
결과메세지

data 객체

└pktHashAN(64)영문+숫자, 최대 64byte*75ac014c33165f3ee0c331123a0049f37a6e1578f8cec1d3d0374ffb75f18496
응답 해쉬값
└bankCdAN(3)영문+숫자, 최대 3byte*089
가상계좌 은행코드
└vAcntNoN(14)숫자, 최대 14byte*AES-256AES-256/ECB/PKCS5Padding01012345678
발급된 가상계좌번호
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└expireDateN(14)숫자, 최대 14byte*20211231235959
입금만료일시 (yyyyMMddHHmmss)
└prdtNmAHN(128)영문+한글+숫자, 최대 128byte*테스트상품
상품명
└ordNmAHN(30)영문+한글+숫자, 최대 30byte*홍길동
주문자명
└trdAmtN(9)숫자, 최대 9byte*AES-256AES-256/ECB/PKCS5Padding1000
거래금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└dpstrNmAHN(50)영문+한글+숫자, 최대 50byte*010가상계좌
예금주명
└mchtCustIdAN(50)영문+숫자, 최대 50byte*HongGilDong
상점 고객 아이디

요청 예시

{
  "params": {
    "mchtId": "nxva_sb_il",
    "ver": "0A18",
    "method": "VA",
    "bizType": "A4",
    "encCd": "23",
    "mchtTrdNo": "ORDER20211231100000",
    "trdDt": "20211231",
    "trdTm": "120000",
    "mobileYn": "N",
    "osType": "W"
  },
  "data": {
    "pktHash": "해시값",
    "bankCd": "089",
    "vAcntNo": "AES암호화된휴대폰번호",
    "expireDate": "20211231235959",
    "prdtNm": "테스트상품",
    "sellerNm": "헥토파이낸셜",
    "ordNm": "홍길동",
    "trdAmt": "AES암호화된금액",
    "dpstrNm": "010가상계좌",
    "taxTypeCd": "N",
    "escrAgrYn": "N",
    "csrcIssReqYn": "N",
    "mchtCustId": "HongGilDong"
  }
}

응답 예시

{
  "params": {
    "mchtId": "nxva_sb_il",
    "ver": "0A18",
    "method": "VA",
    "bizType": "A4",
    "encCd": "23",
    "mchtTrdNo": "ORDER20211231100000",
    "trdNo": "STBK_0123456789",
    "trdDt": "20211231",
    "trdTm": "120000",
    "outStatCd": "0021",
    "outRsltCd": "0000",
    "outRsltMsg": "정상적으로 처리되었습니다."
  },
  "data": {
    "pktHash": "응답해시값",
    "bankCd": "089",
    "vAcntNo": "AES암호화된가상계좌번호",
    "expireDate": "20211231235959",
    "prdtNm": "테스트상품",
    "ordNm": "홍길동",
    "trdAmt": "AES암호화된금액",
    "dpstrNm": "010가상계좌",
    "mchtCustId": "HongGilDong"
  }
}
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?