가상계좌 수취 조회 API
PG사에서 수취조회를 하지 않고 가맹점에서 직접 유효성 검증을 수행하는 방식입니다. 고객이 입금하기 전에 헥토파이낸셜에서 가맹점으로 수취 조회 요청을 전송하고, 가맹점에서 유효성을 확인한 후 응답합니다.
가맹점 수취조회 서비스 신청 필수
가맹점 수취조회 기능은 별도 신청이 필요합니다. 영업담당자를 통해 서비스 신청 후 사용 가능합니다.
수취 조회 흐름
구매자
은행
헥토파이낸셜
가맹점
11. 입금 시도
1. 입금 시도
22. 수취 조회 요청
2. 수취 조회 요청
33. 수취 조회 전문 전송
3. 수취 조회 전문 전송
44. 유효성 검증 결과 응답
4. 유효성 검증 결과 응답
55. 수취 조회 결과 전달
5. 수취 조회 결과 전달
66. 입금 처리 (성공 시)
6. 입금 처리 (성공 시)
통신 규격
| 구분 | 내용 |
|---|---|
| 요청 방향 | 헥토파이낸셜 → 가맹점 |
| 응답 방향 | 가맹점 → 헥토파이낸셜 |
| 전송 방식 | POST |
| 요청 Content-Type | application/x-www-form-urlencoded; charset=UTF-8 |
| 응답 Content-Type | application/json |
| 인코딩 | UTF-8 기본 (EUC-KR로 수신한 경우 동일한 인코딩으로 응답) |
요청 파라미터 (헥토파이낸셜 → 가맹점)
타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자예: AN(10) = 영문+숫자, 최대 10byte
헥토파이낸셜 서버에서 가맹점으로 요청하는 파라미터입니다.
└methodA(2)영문, 최대 2byte*결제수단
VA결제수단
VA: 가상계좌 (고정값)└bizTypeAN(2)영문+숫자, 최대 2byte*업무구분
B0업무구분
B0: 결제 (고정값)└mchtIdAN(10)영문+숫자, 최대 10byte*헥토파이낸셜에서 부여하는 고유 상점아이디
nxva_sb_il헥토파이낸셜에서 부여하는 고유 상점아이디
└trdNoAN(40)영문+숫자, 최대 40byte헥토파이낸셜에서 발급한 고유한 거래번호. 회전식/고정식인 경우 필수 응답, 고정무제한은 응답 안함
STFP_PGCAnxva_sb_il0211129135810M1494620헥토파이낸셜에서 발급한 고유한 거래번호. 회전식/고정식인 경우 필수 응답, 고정무제한은 응답 안함
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*상점에서 생성하는 고유한 상점주문번호
ORDER20211231100000상점에서 생성하는 고유한 상점주문번호
└trdDtmN(14)숫자, 최대 14byte*현재 전문을 전송하는 일시 (YYYYMMDDhhmmss)
20221105140259현재 전문을 전송하는 일시 (YYYYMMDDhhmmss)
└trdAmtN(12)숫자, 최대 12byte*거래금액
1000거래금액
└bankCdAN(3)영문+숫자, 최대 3byte*가상계좌 은행코드
011가상계좌 은행코드
└acntTypeN(1)숫자, 최대 1byte*계좌구분
1계좌구분
1: 기본(회전식) 2: 고정식 3: 고정무제한└vAcntNoN(64)숫자, 최대 64byte*가상계좌번호 (상점별 암호화 방식)
1234567890가상계좌번호 (상점별 암호화 방식)
└mediaTypeN(2)숫자, 최대 2byte고객이 입금/이체에 사용한 매체의 코드
00고객이 입금/이체에 사용한 매체의 코드
└rcptTypeA(1)영문, 최대 1byte*수취조회 구분 코드
N수취조회 구분 코드
N: 수취조회 P: P 수취조회*P수취조회 지원 은행 및 2회 전송 동작은 아래 '수취조회 구분 (N / P)' 섹션을 참고하세요.
└pktHashAN(64)영문+숫자, 최대 64byte*SHA256 방식으로 생성한 해쉬값
6056160d8f24c3ad15a015a0a666b5584c9471c2f8f56945482ca3e656bd0125SHA256 방식으로 생성한 해쉬값
요청 전문 해쉬 코드
| 항목 | 조합 필드 |
|---|---|
| pktHash | 결제수단 + 업무구분 + 거래일시 + 상점아이디 + 거래번호 + 거래금액 + 해쉬키 |
NOTE
해쉬 생성 조합
method + bizType + trdDtm + mchtId + trdNo + trdAmt(평문) + hashKey
매체 코드
| 코드 | 코드명 | 비고 |
|---|---|---|
| 00 | 기타 | 은행에서 정보 미제공시 "00" 설정 |
| 01 | 당행창구 | |
| 02 | 타행창구 | |
| 03 | 당행 CD/ATM | |
| 04 | 타행 CD/ATM | |
| 05 | 텔레뱅킹 | |
| 06 | 인터넷뱅킹 | |
| 07 | 스마트뱅킹 | |
| 08 | 전자금융공동망 | |
| 09 | 자동이체입금 | 지로, CMS, VAN 자금, 납부자 등 |
| 10 | 실시간이체 | |
| 11 | 무인공과금 |
수취조회 구분 (N / P)
rcptType은 이번 요청이 일반 수취조회(N)인지 P수취조회(P)인지를 구분합니다.
P수취조회 지원 은행은 수취조회가 2회 전송될 수 있습니다
P수취조회를 지원하는 은행은 하나의 입금 건에 대해 일반 수취조회(N)와 P수취조회(P)가 각각 전송되어, 수취조회 요청이 최대 2회 발생할 수 있습니다. 중복 수신을 원치 않으면 P수취조회(P)만 수신하도록 설정을 신청할 수 있습니다. (영업담당자 문의)
은행별 P수취조회 지원 여부
| 은행코드 | 은행명 | P수취조회 |
|---|---|---|
| 003 | IBK기업은행 | Y |
| 004 | KB국민은행 | Y |
| 011 | NH농협은행 | Y |
| 020 | 우리은행 | Y |
| 023 | SC제일은행 | N |
| 031 | iM뱅크(대구은행) | Y |
| 032 | 부산은행 | N |
| 034 | 광주은행 | N |
| 039 | 경남은행 | Y |
| 071 | 우체국 | Y |
| 081 | 하나은행(KEB하나은행) | Y |
| 088 | 신한은행 | Y |
| 089 | 케이뱅크 | Y |
NOTE
우체국 P수취조회 예외
우체국은 P수취조회를 지원하지만, ATM·창구 등 현금성 매체로 입금하는 경우에는 통지성 전문이 수신되어 P수취조회가 전송되지 않습니다.
응답 파라미터 (가맹점 → 헥토파이낸셜)
가맹점에서 헥토파이낸셜로 응답하는 파라미터입니다.
└rsltCdN(4)숫자, 최대 4byte*결과코드
0000결과코드
0000: 정상 0001: 계좌없음 0002: 입금기한 만료 0003: 금액오류 0004: 허용되지 않은 매체 0009: 기타오류└rsltMsgAHN(200)영문+한글+숫자, 최대 200byte*결과메세지
정상적으로 처리되었습니다.결과메세지
*가맹점 내부 참고용으로 작성하세요.
응답 결과코드
| 결과코드 | 결과메시지 | 설명 |
|---|---|---|
| 0000 | 정상 | 수취조회 성공, 입금 허용 |
| 0001 | 계좌없음 | 해당 가상계좌가 존재하지 않음 |
| 0002 | 입금기한 만료 | 가상계좌 입금기한이 만료됨 |
| 0003 | 금액오류 | 입금금액이 채번금액과 일치하지 않음 |
| 0004 | 허용되지 않은 매체 | 해당 매체로의 입금이 허용되지 않음 |
| 0009 | 기타오류 | 기타 오류 발생 |
응답 예시
성공
{
"rsltCd": "0000",
"rsltMsg": "정상적으로 처리되었습니다."
}
실패 (입금기한 만료)
{
"rsltCd": "0002",
"rsltMsg": "입금기한이 만료되었습니다."
}
실패 (금액오류)
{
"rsltCd": "0003",
"rsltMsg": "입금금액이 일치하지 않습니다."
}
가맹점 구현 가이드
NOTE
수취조회 처리 로직
가맹점에서는 수취조회 요청을 받으면 해당 주문의 유효성(계좌 존재, 입금기한, 금액)을 확인하고 결과를 응답해야 합니다.
구현 체크리스트
- 계좌 존재 여부 확인:
mchtTrdNo또는vAcntNo로 주문 조회 - 입금기한 확인: 현재 시간이 입금기한 이전인지 확인
- 금액 확인:
trdAmt가 채번 시 설정한 금액과 일치하는지 확인 - 해쉬 검증:
pktHash값 검증으로 데이터 위변조 확인
샘플 코드 (Node.js)
app.post('/api/receipt-inquiry', (req, res) => {
const { mchtTrdNo, trdAmt, vAcntNo, pktHash } = req.body;
// 1. 해쉬 검증
if (!verifyHash(req.body, pktHash)) {
return res.json({ rsltCd: '0009', rsltMsg: '해쉬 검증 실패' });
}
// 2. 주문 조회
const order = findOrderByTrdNo(mchtTrdNo);
if (!order) {
return res.json({ rsltCd: '0001', rsltMsg: '계좌없음' });
}
// 3. 입금기한 확인
if (new Date() > order.expireDate) {
return res.json({ rsltCd: '0002', rsltMsg: '입금기한 만료' });
}
// 4. 금액 확인
if (order.amount !== parseInt(trdAmt)) {
return res.json({ rsltCd: '0003', rsltMsg: '금액오류' });
}
// 5. 성공 응답
return res.json({ rsltCd: '0000', rsltMsg: '정상' });
});
요청/응답 예시
수취 조회 요청 (헥토파이낸셜 → 가맹점)
POST /your-receipt-inquiry-url HTTP/1.1
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
method=VA
&bizType=B0
&mchtId=nxva_sb_il
&trdNo=STFP_PGVAnxva_sb_il0211231100000M1234567
&mchtTrdNo=ORDER20211231100000
&trdDtm=20211231120000
&trdAmt=50000
&bankCd=011
&acntType=1
&vAcntNo=12345678901234
&mediaType=06
&rcptType=N
&pktHash=6056160d8f24c3ad15a015a0a666b5584c9471c2f8f56945482ca3e656bd0125
응답 - 성공 (가맹점 → 헥토파이낸셜)
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"rsltCd": "0000",
"rsltMsg": "정상"
}
응답 - 실패 (가맹점 → 헥토파이낸셜)
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"rsltCd": "0003",
"rsltMsg": "금액오류"
}
