가상계좌 노티 전문
가상계좌는 다른 결제수단과 달리 채번, 입금, 취소, 환불 등 거래 단계마다 노티가 발송됩니다. 노티 유형별로 처리 로직을 구현해야 합니다.
노티 유형 총정리
가상계좌 노티는 outStatCd(거래상태)와 bizType(업무구분) 조합으로 구분합니다.
| 노티 유형 | outStatCd | bizType | 거래 상태 | 발생 시점 |
|---|---|---|---|---|
| 채번 완료 | 0051 | A0 | 입금 대기 | 가상계좌 발급 시 (고정식 무제한 제외) |
| 입금 완료 | 0021 | B1 | 결제 완료 | 고객이 입금 완료 시 |
| 채번 취소 | 0021 | A2 | 발급 취소 | 가맹점에서 채번 취소 API 호출 시 |
| 자동취소 | 0121 | B2 | 입금 후 취소 | 입금 후 은행 사유로 거래가 취소된 경우 (설정 활성화 시) |
| 환불 완료 | 0021 | C0 | 환불 완료 | 환불 API 호출 후 등록 완료 시 |
NOTE
010 가상계좌 노티는 별도 문서 참고
010 가상계좌(bizType=A4)의 채번/입금 노티 전문은 010 가상계좌 전용 노티 문서를 참고하세요.
노티 수신 URL
노티는 헥토파이낸셜 서버가 가맹점 서버로 직접 보내는 Server-to-Server 요청이며, 아래 3가지 URL 중 하나로 전송됩니다. 자세한 개념은 결과통보 URL 가이드를 참고하세요.
| 표기 | 의미 |
|---|---|
| 요청 notiUrl | 채번 요청 시 전달한 notiUrl 파라미터 |
| 기준정보 URL | 영업 담당자를 통해 상점 기준정보에 등록한 노티 URL |
| 기준정보 수취조회 URL | 상점 기준정보에 등록한 수취조회 전용 URL (기준정보 URL과 별도) |
계좌 유형·노티 유형별 수신 URL입니다. A → B는 A가 없으면 B로 전송된다는 뜻입니다.
| 노티 유형 | 회전식 / 고정식 | 고정식 무제한 |
|---|---|---|
| 채번 완료 | 요청 notiUrl → 기준정보 URL | 발송 안 함 |
| 입금 완료 | 요청 notiUrl → 기준정보 URL | 기준정보 URL |
| 채번 취소 | 기준정보 URL → 요청 notiUrl | 기준정보 URL |
| 수취조회 / P수취조회 | 기준정보 수취조회 URL | 기준정보 수취조회 URL |
핵심 요약
채번 취소는 다른 노티와 반대로 기준정보 URL이 우선입니다.
고정식 무제한은 요청 notiUrl이 없으므로 기준정보 URL을 반드시 등록해야 노티를 받을 수 있습니다.
계좌 유형별 차이
acntType으로 계좌 유형을 구분합니다. 고정식 무제한(3)은 전송 파라미터가 다릅니다.
| 구분 | 회전식(1) / 고정식(2) | 고정식 무제한(3) |
|---|---|---|
| 채번 완료 노티 | 발송 | 발송 안 함 |
| mchtTrdNo | 채번 시 주문번호 | 항상 0000000 — vAcntNo로 주문 구분 |
| trdNo | 채번 시 발급된 거래번호 | 입금 건별 거래번호 — 환불 시 orgTrdNo로 사용 |
처리 시 유의사항
입금 기한(expireDt)이 지나도 노티가 오지 않습니다. 만료 처리는 가맹점에서 직접 해야 합니다.
입금자명(dpstrNm)은 주문 시 입력한 이름과 다를 수 있어 참고용으로만 사용하세요.
환불 완료 노티 수신 시점에 환불 완료로 처리하세요. 고객 계좌 입금은 익 영업일이며 이후 노티는 없습니다.
통신 규격
| 구분 | 내용 |
|---|---|
| 전송 방식 | POST |
| Content-Type | application/x-www-form-urlencoded; charset=UTF-8 |
| 응답 형식 | Plain Text (OK 또는 FAIL) |
노티 파라미터 — 회전식 / 고정식
회전식(acntType=1) 및 고정식(acntType=2) 가상계좌에서 전송되는 노티 파라미터입니다.
채번 완료(0051), 입금 완료(0021), 자동취소(0121, 설정 활성화 시) 등 모든 노티 유형에서 사용됩니다.
타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자예: AN(10) = 영문+숫자, 최대 10byte
└outStatCdN(4)숫자, 최대 4byte*거래상태
0021거래상태
0021: 성공 (입금 완료/채번 취소/환불 — bizType으로 구분) 0051: 입금 대기 중 (채번 완료) 0121: 자동취소 (설정 활성화 시)└trdNoAN(40)영문+숫자, 최대 40byte*헥토파이낸셜에서 부여하는 고유 거래번호
STFP_PGVAnxva_jt_il0211129135810M1494620헥토파이낸셜에서 부여하는 고유 거래번호
└methodA(2)영문, 최대 2byte*결제수단
VA결제수단
VA: 가상계좌└bizTypeAN(2)영문+숫자, 최대 2byte*업무구분
A0업무구분
A0: 채번 A2: 채번취소 B1: 입금통보 B2: 자동취소 (설정 활성화 시) C0: 환불└mchtIdAN(12)영문+숫자, 최대 12byte*헥토파이낸셜에서 부여하는 상점아이디
nxva_jt_il헥토파이낸셜에서 부여하는 상점아이디
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*상점에서 생성하는 고유 주문 번호
ORDER20211231100000상점에서 생성하는 고유 주문 번호
└mchtCustNmAHN(30)영문+한글+숫자, 최대 30byte주문자명
가맹점명_홍길동주문자명
└mchtNameAHN(20)영문+한글+숫자, 최대 20byte실 판매자명. 거래 요청 시 실 판매자명이 없으면 헥토파이낸셜과 계약된 상점명
헥토파이낸셜실 판매자명. 거래 요청 시 실 판매자명이 없으면 헥토파이낸셜과 계약된 상점명
└pmtprdNmAHN(128)영문+한글+숫자, 최대 128byte고객이 주문한 결제 상품명
테스트상품고객이 주문한 결제 상품명
└trdDtmN(14)숫자, 최대 14byte*거래일시. 형식: YYYYMMDDhhmmss
20211231100000거래일시. 형식: YYYYMMDDhhmmss
└trdAmtN(12)숫자, 최대 12byte거래금액
1000거래금액
└bankCdAN(10)영문+숫자, 최대 10byte은행 코드
011은행 코드
└bankNmAHN(10)영문+한글+숫자, 최대 10byte은행명
NH농협은행명
└acntTypeN(1)숫자, 최대 1byte계좌구분
1계좌구분
1: 기본(회전식) 2: 고정식 3: 고정식 무제한└vAcntNoN(64)숫자, 최대 64byte가상계좌번호
0123456789가상계좌번호
└expireDtN(14)숫자, 최대 14byte가상계좌 입금만료일시
20271231235959가상계좌 입금만료일시
└AcntPrintNmAHN(12)영문+한글+숫자, 최대 12byte고객 통장에 찍힐 이름. 결제 요청 시 전달한 값이며, 없으면 헥토파이낸셜과 계약된 상점명
헥토파이낸셜고객 통장에 찍힐 이름. 결제 요청 시 전달한 값이며, 없으면 헥토파이낸셜과 계약된 상점명
└dpstrNmAHN(30)영문+한글+숫자, 최대 30byte가상계좌에 실제 입금한 사람의 이름 (입금 노티에서 전달)
홍길동가상계좌에 실제 입금한 사람의 이름 (입금 노티에서 전달)
└emailAN(60)영문+숫자, 최대 60byte상점 고객 이메일
HongGilDong@example.com상점 고객 이메일
└mchtCustIdAN(50)영문+숫자, 최대 50byte상점 고객 아이디
HongGilDong상점 고객 아이디
└orgTrdNoAN(40)영문+숫자, 최대 40byte원거래번호 (취소·환불 시)
STFP_PGVAnxva_jt_il0211129135810M1494620원거래번호 (취소·환불 시)
└orgTrdDtN(8)숫자, 최대 8byte원거래일자 (취소·환불 시)
20211231원거래일자 (취소·환불 시)
└csrcIssNoAN(9)영문+숫자, 최대 9byte현금영수증 승인번호
0123456789현금영수증 승인번호
└cnclTypeN(2)숫자, 최대 2byte취소 유형
00취소 유형
00: 전체 취소 10: 부분 취소└mchtParamAHN(4000)영문+한글+숫자, 최대 4000byte요청 시 전달한 값을 그대로 반환합니다.
name=HongGilDong&age=25요청 시 전달한 값을 그대로 반환합니다.
└pktHashAN(64)영문+숫자, 최대 64byte*SHA256 해시값
a2d6d597d55d7c9b689baa2e08c1ddf0ce71f4248c5b9b59fe61bfbf949543e1SHA256 해시값
NOTE
해시 생성 조합
outStatCd + 거래일자(trdDtm 앞 8자리) + 거래시간(trdDtm 뒤 6자리) + mchtId + mchtTrdNo + trdAmt(평문) + hashKey
노티 파라미터 — 고정식 무제한
고정식 무제한(acntType=3) 가상계좌에서 전송되는 노티 파라미터입니다.
고정식 무제한 전용 특이사항
고정식 무제한 계좌는 채번 노티(outStatCd=0051)를 발송하지 않습니다. 기본적으로 입금 완료 노티(outStatCd=0021 / bizType=B1)를 수신하며, 자동취소 노티를 활성화한 경우 자동취소 노티(outStatCd=0121 / bizType=B2)도 수신됩니다. 또한 mchtTrdNo가 항상 '0000000'으로 고정되어 개별 주문을 식별할 수 없으므로, vAcntNo(가상계좌번호)로 주문을 구분해야 합니다.
타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자예: AN(10) = 영문+숫자, 최대 10byte
└outStatCdN(4)숫자, 최대 4byte*거래상태. 기본 입금 완료 노티는 0021이며, 자동취소 노티 활성화 시 0121도 수신
0021거래상태. 기본 입금 완료 노티는 0021이며, 자동취소 노티 활성화 시 0121도 수신
0021: 입금 완료 0121: 자동취소 (설정 활성화 시)└trdNoAN(40)영문+숫자, 최대 40byte*헥토파이낸셜에서 부여하는 고유 거래번호
STFP_PGVAnxva_fix20211129135810M1494620헥토파이낸셜에서 부여하는 고유 거래번호
*고정식 무제한은 입금 건별로 발급되는 거래번호로, 채번 시 발급된 거래번호와 다릅니다. 환불 등 후속 거래의 원거래번호(orgTrdNo)로는 이 입금 거래번호를 사용합니다.
└methodA(2)영문, 최대 2byte*결제수단
VA결제수단
VA: 가상계좌└bizTypeAN(2)영문+숫자, 최대 2byte*업무구분. 기본 입금통보는 B1이며, 자동취소 노티 활성화 시 B2도 수신
B1업무구분. 기본 입금통보는 B1이며, 자동취소 노티 활성화 시 B2도 수신
B1: 입금통보 B2: 자동취소 (설정 활성화 시)└mchtIdAN(12)영문+숫자, 최대 12byte*헥토파이낸셜에서 부여하는 상점아이디
nxva_fix2헥토파이낸셜에서 부여하는 상점아이디
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*고정식 무제한 계좌는 항상 '0000000'으로 고정 전송됩니다. vAcntNo로 주문을 구분하세요.
0000000고정식 무제한 계좌는 항상 '0000000'으로 고정 전송됩니다. vAcntNo로 주문을 구분하세요.
└trdDtmN(14)숫자, 최대 14byte*거래일시. 형식: YYYYMMDDhhmmss
20211231100000거래일시. 형식: YYYYMMDDhhmmss
└trdAmtN(12)숫자, 최대 12byte거래금액
1000거래금액
└bankCdAN(10)영문+숫자, 최대 10byte은행 코드
011은행 코드
└bankNmAHN(10)영문+한글+숫자, 최대 10byte은행명
NH농협은행명
└acntTypeN(1)숫자, 최대 1byte계좌구분. 고정식 무제한은 항상 3
3계좌구분. 고정식 무제한은 항상 3
3: 고정식 무제한└vAcntNoN(64)숫자, 최대 64byte가상계좌번호. mchtTrdNo가 고정값이므로 이 필드로 주문을 구분해야 합니다.
0123456789가상계좌번호. mchtTrdNo가 고정값이므로 이 필드로 주문을 구분해야 합니다.
└expireDtN(14)숫자, 최대 14byte가상계좌 입금만료일시
20271231235959가상계좌 입금만료일시
└AcntPrintNmAHN(12)영문+한글+숫자, 최대 12byte고객 통장에 찍힐 이름. 결제 요청 시 전달한 값이며, 없으면 헥토파이낸셜과 계약된 상점명
헥토파이낸셜고객 통장에 찍힐 이름. 결제 요청 시 전달한 값이며, 없으면 헥토파이낸셜과 계약된 상점명
└dpstrNmAHN(30)영문+한글+숫자, 최대 30byte가상계좌에 실제 입금한 사람의 이름
홍길동가상계좌에 실제 입금한 사람의 이름
└pktHashAN(64)영문+숫자, 최대 64byte*SHA256 해시값
a2d6d597d55d7c9b689baa2e08c1ddf0ce71f4248c5b9b59fe61bfbf949543e1SHA256 해시값
NOTE
해시 생성 조합
outStatCd + 거래일자(trdDtm 앞 8자리) + 거래시간(trdDtm 뒤 6자리) + mchtId + mchtTrdNo + trdAmt(평문) + hashKey
노티 응답 (가맹점 → 헥토파이낸셜)
가맹점에서 헥토파이낸셜로 응답을 전송합니다.
| 응답 | 설명 |
|---|---|
OK | 성공 (대문자). 노티 수신 완료로 처리됩니다. |
FAIL 또는 그 외 | 실패로 인식하여 상점별 설정된 횟수까지 재전송합니다. 재전송 기준일 초과 시 전송이 중단됩니다. |
응답 형식 주의
응답은 Plain Text로 'OK'만 보내야 합니다. 공백이나 다른 문자가 포함되면 실패로 간주되어 재전송이 발생할 수 있습니다.
NOTE
채번 노티와 입금 노티 구분
outStatCd만으로는 노티 유형을 구분할 수 없습니다. 0021은 입금 완료·채번 취소·환불에 공통으로 쓰이므로 bizType을 함께 확인하세요. 실제 결제 처리는 입금 완료 노티(0021 / B1)에서 수행하세요.
해시 검증
해시 검증 필수
데이터 위변조를 체크하기 위해 notiUrl로 받은 해시값을 반드시 검증해야 합니다. 일치하는 경우에만 서비스를 제공하세요.
| 항목 | 조합 필드 |
|---|---|
| pktHash | 거래상태코드 + 거래일자(trdDtm 앞 8자리) + 거래시간(trdDtm 뒤 6자리) + 상점아이디 + 상점주문번호 + 거래금액(평문) + 해시키 |
노티 예시
입금 노티 — 회전식 / 고정식 (헥토파이낸셜 → 가맹점)
POST /your-noti-url HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
outStatCd=0021
&trdNo=STFP_PGVAnxva_sb_il0211231100000M1234567
&method=VA
&bizType=B1
&mchtId=nxva_sb_il
&mchtTrdNo=ORDER20211231100000
&mchtCustNm=홍길동
&mchtName=헥토파이낸셜
&pmtprdNm=테스트상품
&trdDtm=20211231120000
&trdAmt=50000
&bankCd=011
&vAcntNo=12345678901234
&dpstrNm=홍길동
&acntType=1
&email=test@example.com
&mchtCustId=customer123
&csrcIssNo=
&mchtParam=
&pktHash=a2d6d597d55d7c9b689baa2e08c1ddf0ce71f4248c5b9b59fe61bfbf949543e1
입금 노티 — 고정식 무제한 (헥토파이낸셜 → 가맹점)
POST /your-noti-url HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
outStatCd=0021
&trdNo=STFP_PGVAnxva_fix20211231120000M9876543
&method=VA
&bizType=B1
&mchtId=nxva_fix2
&mchtTrdNo=0000000
&trdDtm=20211231120000
&trdAmt=50000
&bankCd=011
&bankNm=NH농협
&vAcntNo=2022011000001
&dpstrNm=홍길동
&acntType=3
&AcntPrintNm=헥토파이낸셜
&expireDt=20271231235959
&pktHash=b3e7f498c66e8d1a790cbb3f9dc2eef1b48a5c2594c6a0ae2f72cge059654f2
응답 (가맹점 → 헥토파이낸셜)
OK
