헥토파이낸셜 개발자센터

가상계좌 채번 API

결제창 없이 서버에서 직접 가상계좌를 발급하는 API입니다. 회전식과 고정식 두 가지 방식을 지원합니다.

테스트용 키 정보

주의 사항

가상계좌 입금 주의사항

입금금액이 설정된 금액과 정확히 일치해야 자동 승인됩니다. 만료일 이후에는 입금이 불가능합니다.
  • 가상계좌는 발급 후 만료일까지 유효합니다.
  • 만료일 이후에는 입금이 불가능합니다.
  • 가상계좌번호는 고유하며, 중복 발급되지 않습니다.
  • 입금 완료 시 노티(결과통보)를 받을 수 있습니다.
  • 회전식(acntType=1): 매 채번 시 새 가상계좌번호가 발급됩니다.
  • 고정식(acntType=2): 고정된 가상계좌번호에 금액을 설정하여 입금받습니다.
  • 가상계좌 은행코드는 가상계좌 은행 코드 목록 참고 바랍니다.

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*
헥토파이낸셜에서 부여하는 고유 상점아이디
nx_mid_il: 회전식 nxva_fix: 고정식
└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(64)영문+숫자, 최대 64byte*SHA-256(실시간 생성)
SHA256 방식으로 생성한 해쉬값
NOTE

해쉬 생성 조합

trdDt + trdTm + mchtId + mchtTrdNo + trdAmt(평문) + hashKey
└bankCdAN(3)영문+숫자, 최대 3byte*
가상계좌 은행코드
*가상계좌 은행 코드 목록 참고
└acntTypeN(1)숫자, 최대 1byte*
계좌구분
1: 회전식 2: 고정식 3: 고정식무제한
*고정식무제한(3)은 trdAmt를 0으로 설정하고, 현금영수증 API를 별도 호출해야 합니다
└vAcntNoN(16)숫자, 최대 16byteAES-256AES-256/ECB/PKCS5Padding + Base64
가상계좌번호 (고정식일 경우에만 사용)
*acntType=2 (고정식)일 경우에만 사용합니다.
└trdAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding + Base64
거래금액
*입금 예정 금액. 이 금액으로 입금 시 자동 승인
└prdtNmAHN(128)영문+한글+숫자, 최대 128byte*
상품명
└sellerNmAHN(128)영문+한글+숫자, 최대 128byte*
판매자명
└expireDateN(14)숫자, 최대 14byte
가상계좌 입금기한 (YYYYMMDDhhmmss)
*설정하지 않으면 기본 만료일(D+10)이 적용
└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
거래금액 중 면세금액 (복합과세일 경우 필수)
└escrAgrYnA(1)영문, 최대 1byte*
에스크로 사용여부
Y: 에스크로 사용 N: 에스크로 미사용
└escrPwdAN(64)영문+숫자, 최대 64byteAES-256AES-256/ECB/PKCS5Padding + Base64
에스크로 비밀번호 (에스크로 사용시 필수)
*escrAgrYn=Y일 경우 필수
└rfdDpstrNmAHN(50)영문+한글+숫자, 최대 50byteAES-256AES-256/ECB/PKCS5Padding + Base64
에스크로 환불 예금주명 (에스크로 사용시 필수)
*escrAgrYn=Y일 경우 필수
└csrcIssReqYnA(1)영문, 최대 1byte*
현금영수증 발행여부
Y: 현금영수증 발행 N: 현금영수증 미발행
└cashRcptPrposDivCdN(1)숫자, 최대 1byte
현금영수증 용도구분코드 (현금영수증 발행시 필수)
0: 소득공제 1: 지출증빙
*csrcIssReqYn=Y일 경우 필수
└csrcRegNoDivCdN(1)숫자, 최대 1byte
현금영수증 등록번호 구분코드 (현금영수증 발행시 필수)
1: 카드 2: 주민번호 3: 사업자번호 4: 휴대폰번호
*csrcIssReqYn=Y일 경우 필수
└csrcRegNoN(18)숫자, 최대 18byteAES-256AES-256/ECB/PKCS5Padding + Base64
현금영수증 고유식별정보 (현금영수증 발행시 필수)
*csrcIssReqYn=Y일 경우 필수. 주민등록번호/사업자번호/휴대폰번호/카드번호 중 해당 값 입력
└ordNmAHN(30)영문+한글+숫자, 최대 30byte
주문자명
└dpstrNmAHN(50)영문+한글+숫자, 최대 50byte
통장인자명
*고객의 통장에 찍힐 인자명. 공백일 경우 sellerNm(판매자명)을 통장인자명으로 사용
└emailAN(60)영문+숫자, 최대 60byteAES-256AES-256/ECB/PKCS5Padding + Base64
고객 이메일주소 (에스크로 사용시 필수)
*escrAgrYn=Y일 경우 필수
└mchtCustIdAN(50)영문+숫자, 최대 50byte
상점 고객아이디
└notiUrlAN(250)영문+숫자, 최대 250byte*
입금완료 후, 헥토파이낸셜에서 상점으로 전달하는 노티(결과통보)를 수신하는 Callback URL
└mchtParamAHN(4000)영문+한글+숫자, 최대 4000byte
기타 주문 정보를 입력하는 상점 예약 필드

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

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

상점아이디(mchtId)은행코드(bankCd)가상계좌번호(vAcntNo)
nxva_fix004 (국민은행)2022004000001 ~ 2022004000050
nxva_fix011 (농협은행)2022011000001 ~ 2022011000050

응답 파라미터

타입 표기법
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*
SHA256 방식으로 생성한 해쉬값
NOTE

해쉬 생성 조합

outStatCd + trdDt + trdTm + mchtId + mchtTrdNo + trdAmt(평문) + hashKey
└trdAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding1000
거래금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└bankCdAN(3)영문+숫자, 최대 3byte*004
가상계좌 은행코드
└vAcntNoN(16)숫자, 최대 16byte*AES-256AES-256/ECB/PKCS5Padding12345678901234
발급된 가상계좌번호
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└expireDateN(14)숫자, 최대 14byte*20271231235959
가상계좌 입금기한 (YYYYMMDDhhmmss)
└acntTypeN(1)숫자, 최대 1byte*1
계좌구분 (요청시 값 그대로 전달)
1: 회전식 2: 고정식 3: 고정무제한

노티 전문 (결과통보)

고객이 가상계좌에 입금하면, 헥토파이낸셜에서 가맹점으로 노티(결과통보) 메세지가 전송됩니다.

2단계 노티 처리 필수

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

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?