헥토파이낸셜 개발자센터

가상계좌 노티 전문

가상계좌는 다른 결제수단과 달리 여러 단계에서 노티가 발송됩니다. 각 노티 유형을 정확히 이해하고 처리해야 합니다.

다단계 노티 처리 필수

가상계좌는 계좌 발급, 입금 완료, 취소, 환불 등 각 단계에서 노티가 전송됩니다. 각 노티 유형에 맞는 처리 로직을 구현해야 합니다.

노티 유형 총정리

가상계좌에서 발생하는 모든 노티 유형입니다. outStatCd와 bizType을 조합하여 노티 유형을 구분합니다.

노티 유형outStatCdbizType발생 시점가맹점 처리
채번 완료0051A0가상계좌 발급 시 (고정식 무제한 제외)계좌번호 안내, 입금 대기 상태로 변경
입금 완료0021B1고객이 입금 완료 시결제 완료 처리, 상품/서비스 제공
채번 취소0021A2가맹점에서 채번 취소 API 호출 시주문 취소 처리
자동취소0121B2입금 후 은행 이슈로 거래 취소 발생 시거래 취소 처리 (영업 담당자 요청 시 활성화)
환불 완료0021C0환불 API 호출 후 등록 완료 시환불 완료 상태로 변경 (고객 실제 입금은 익 영업일, 이후 별도 노티 없음)
NOTE

010 가상계좌 노티는 별도 문서 참고

010 가상계좌(bizType=A4)의 채번/입금 노티 전문은 010 가상계좌 전용 노티 문서를 참고하세요.

고정식 무제한 — 채번 노티 미발송

acntType=3(고정식 무제한) 계좌는 채번 완료 노티(0051)가 발송되지 않으며, 기본적으로 입금 완료 노티(0021/B1)를 수신합니다. 자동취소 노티를 활성화한 경우에는 자동취소 노티(0121/B2)도 수신됩니다. 전송 파라미터가 회전식/고정식과 다르므로 아래 각 섹션을 구분하여 처리하세요.

노티 유형별 상세

1. 채번 완료 노티

outStatCd: 0051 bizType: A0

고객이 결제창에서 가상계좌를 선택하고 발급이 완료되면 전송됩니다.

가맹점 처리 사항:

  • 발급된 가상계좌번호(vAcntNo)와 입금기한(expireDt)을 고객에게 안내
  • 주문 상태를 "입금 대기" 상태로 변경
  • 아직 결제가 완료된 것이 아니므로 상품/서비스 제공 금지

주요 파라미터:

  • vAcntNo: 발급된 가상계좌번호
  • bankNm, bankCd: 은행 정보
  • expireDt: 입금 만료 일시
  • trdAmt: 입금해야 할 금액

2. 입금 완료 노티

outStatCd: 0021 bizType: B1

고객이 발급된 가상계좌에 입금을 완료하면 전송됩니다.

가맹점 처리 사항:

  • 실제 결제 완료 처리 (재고 차감, 주문 확정 등)
  • 상품/서비스 제공 시작
  • 고객에게 결제 완료 안내

주요 파라미터:

  • dpstrNm: 실제 입금자명 (채번 시 입력한 이름과 다를 수 있음)
  • trdAmt: 입금된 금액
  • csrcIssNo: 현금영수증 승인번호 (발급된 경우, 회전식/고정식만)
NOTE

입금자명 불일치

dpstrNm(실제 입금자명)이 주문 시 입력한 이름과 다를 수 있습니다. 타인 계좌로 입금하는 경우가 있으므로 참고용으로만 사용하세요.

3. 채번 취소 노티

outStatCd: 0021 bizType: A2

가맹점에서 채번 취소 API를 호출했을 때 전송됩니다.

가맹점 처리 사항:

  • 주문 상태를 "취소"로 변경
  • 고객에게 결제 취소 안내

입금 기한 만료 시 노티 없음

입금 기한(expireDt)이 만료되어도 별도의 노티가 발송되지 않습니다. 가맹점에서 expireDt를 기준으로 직접 만료 처리 로직을 구현해야 합니다.

4. 자동취소 노티

outStatCd: 0121 bizType: B2

고객 입금 후 은행 이슈(계좌 오류, 한도 초과 등)로 거래가 자동 취소될 때 전송됩니다. 자동취소 노티 설정이 활성화된 가맹점에만 전송됩니다.

영업 담당자 요청 후 사용 가능

자동취소 노티는 기본 제공되지 않으며, 영업 담당자에게 요청하여 설정을 활성화해야 수신됩니다.

가맹점 처리 사항:

  • 주문 상태를 "취소"로 변경
  • 고객에게 결제 취소 및 재결제 안내

5. 환불 완료 노티

outStatCd: 0021 bizType: C0

가맹점에서 환불 API를 호출하고 헥토파이낸셜에서 환불 등록이 완료되면 전송됩니다.

고객 계좌 실제 입금은 익 영업일 — 이후 별도 노티 없음

이 노티 수신 시점에 가맹점은 환불 완료로 처리하면 됩니다. 고객 계좌로의 실제 입금은 익 영업일에 처리되며, 입금 완료 시 별도 노티는 발송되지 않습니다.

가맹점 처리 사항:

  • 주문 상태를 "환불 완료"로 변경
  • 고객에게 환불 완료 안내 (계좌 입금은 익 영업일 예정임을 함께 안내)

주요 파라미터:

  • orgTrdNo: 원거래 번호
  • orgTrdDt: 원거래 일자
  • cnclType: 취소 유형 (00: 전체, 10: 부분)
NOTE

notiUrl이란?

notiUrl은 PG사 서버에서 가맹점 서버로 직접 결제 결과를 전송하는 Server-to-Server 방식의 웹훅입니다. 브라우저를 거치지 않아 안정적으로 결과를 수신할 수 있습니다.

자세한 설명은 결과통보 URL 가이드를 참고하세요.

통신 규격

구분내용
전송 방식POST
Content-Typeapplication/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*20211231100000
거래일시. 형식: YYYYMMDDhhmmss
└trdAmtN(12)숫자, 최대 12byte1000
거래금액
└bankCdAN(10)영문+숫자, 최대 10byte011
은행 코드
└bankNmAHN(10)영문+한글+숫자, 최대 10byteNH농협
은행명
└acntTypeN(1)숫자, 최대 1byte1
계좌구분
1: 기본(회전식) 2: 고정식 3: 고정무제한
└vAcntNoN(64)숫자, 최대 64byte0123456789
가상계좌번호
└expireDtN(14)숫자, 최대 14byte20271231235959
가상계좌 입금만료일시
└AcntPrintNmAHN(12)영문+한글+숫자, 최대 12byte헥토파이낸셜
고객의 통장에 찍힐 통장인자명. 결제요청시 전달된 값으로 전달. 값이 없는 경우는 헥토파이낸셜와 계약된 상점명
└dpstrNmAHN(30)영문+한글+숫자, 최대 30byte홍길동
가상계좌에 실제 입금한 사람의 이름 (입금노티에서 전달)
└emailAN(60)영문+숫자, 최대 60byteHongGilDong@example.com
상점 고객 이메일
└mchtCustIdAN(50)영문+숫자, 최대 50byteHongGilDong
상점 고객 아이디
└orgTrdNoAN(40)영문+숫자, 최대 40byteSTFP_PGVAnxva_jt_il0211129135810M1494620
취소 시, 원거래 번호
└orgTrdDtN(8)숫자, 최대 8byte20211231
취소 시, 원거래 일자
└csrcIssNoAN(9)영문+숫자, 최대 9byte0123456789
현금영수증 승인번호
└cnclTypeN(2)숫자, 최대 2byte00
취소거래타입
00: 전체 취소 10: 부분 취소
└mchtParamAHN(4000)영문+한글+숫자, 최대 4000bytename=HongGilDong&age=25
상점에서 이용하는 추가 정보 필드로 전달한 값이 그대로 반환됩니다.
└pktHashAN(64)영문+숫자, 최대 64byte*a2d6d597d55d7c9b689baa2e08c1ddf0ce71f4248c5b9b59fe61bfbf949543e1
SHA256 해쉬값
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
거래상태. 기본 입금 완료 노티는 0021이며, 자동취소 노티 활성화 시 0121도 수신
0021: 입금 완료 0121: 자동취소 (설정 활성화 시)
└trdNoAN(40)영문+숫자, 최대 40byte*STFP_PGVAnxva_fix20211129135810M1494620
헥토파이낸셜에서 부여하는 고유 거래번호
*고정식 무제한은 입금 건별로 발급되는 거래번호로, 채번 시 발급된 거래번호와 다릅니다. 환불 등 후속 거래의 원거래번호(orgTrdNo)로는 이 입금 거래번호를 사용합니다.
└methodA(2)영문, 최대 2byte*VA
결제수단
VA: 가상계좌
└bizTypeAN(2)영문+숫자, 최대 2byte*B1
업무구분. 기본 입금통보는 B1이며, 자동취소 노티 활성화 시 B2도 수신
B1: 입금통보 B2: 자동취소 (설정 활성화 시)
└mchtIdAN(12)영문+숫자, 최대 12byte*nxva_fix2
헥토파이낸셜에서 부여하는 상점아이디
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*0000000
고정식 무제한 계좌는 항상 '0000000'으로 고정 전송됩니다. vAcntNo로 주문을 구분하세요.
└trdDtmN(14)숫자, 최대 14byte*20211231100000
거래일시. 형식: YYYYMMDDhhmmss
└trdAmtN(12)숫자, 최대 12byte1000
거래금액
└bankCdAN(10)영문+숫자, 최대 10byte011
은행 코드
└bankNmAHN(10)영문+한글+숫자, 최대 10byteNH농협
은행명
└acntTypeN(1)숫자, 최대 1byte3
계좌구분. 고정식 무제한은 항상 3
3: 고정무제한
└vAcntNoN(64)숫자, 최대 64byte0123456789
가상계좌번호. mchtTrdNo가 고정값이므로 이 필드로 주문을 구분해야 합니다.
└expireDtN(14)숫자, 최대 14byte20271231235959
가상계좌 입금만료일시
└AcntPrintNmAHN(12)영문+한글+숫자, 최대 12byte헥토파이낸셜
고객의 통장에 찍힐 통장인자명. 결제요청시 전달된 값으로 전달. 값이 없는 경우는 헥토파이낸셜와 계약된 상점명
└dpstrNmAHN(30)영문+한글+숫자, 최대 30byte홍길동
가상계좌에 실제 입금한 사람의 이름
└pktHashAN(64)영문+숫자, 최대 64byte*a2d6d597d55d7c9b689baa2e08c1ddf0ce71f4248c5b9b59fe61bfbf949543e1
SHA256 해쉬값
NOTE

해쉬 생성 조합

outStatCd + 거래일자(trdDtm 앞 8자리) + 거래시간(trdDtm 뒤 6자리) + mchtId + mchtTrdNo + trdAmt(평문) + hashKey

노티 응답 (가맹점 → 헥토파이낸셜)

가맹점에서 헥토파이낸셜로 응답을 전송합니다.

응답설명
OK성공 (대문자). 노티 수신 완료로 처리됩니다.
FAIL 또는 그 외실패로 인식하여 상점별 설정된 횟수까지 재전송합니다. 재전송 기준일 초과 시 전송이 중단됩니다.

응답 형식 주의

응답은 Plain Text로 'OK'만 보내야 합니다. 공백이나 다른 문자가 포함되면 실패로 간주되어 재전송이 발생할 수 있습니다.
NOTE

채번노티와 입금노티 구분

outStatCd가 '0051'이면 채번 완료 노티, '0021'이면 입금 완료 노티입니다. 실제 결제 처리는 입금 완료 노티(0021)에서 수행하세요.

해쉬 검증

해쉬 검증 필수

데이터 위변조를 체크하기 위해 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
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?