헥토파이낸셜 개발자센터

가상계좌 환불 API

입금이 완료된 가상계좌 거래에 대해 고객 계좌로 환불을 처리하는 API입니다.

테스트용 키 정보

API 정보

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

주의 사항

가상계좌 환불 주의사항

환불 API 응답(및 C0 노티) 수신 시 가맹점은 환불 완료로 처리하면 됩니다. 고객 계좌로의 실제 입금은 익 영업일에 처리되며, 입금 완료 시 별도 노티는 발송되지 않습니다. 환불 기능은 환불 서비스가 등록된 상점에 한해 사용 가능합니다.
  • 환불 API 응답 및 C0 노티 수신 시점에 환불 완료 처리하면 되며, 실제 고객 계좌 입금은 익 영업일에 처리됩니다. 입금 완료 시 별도 노티는 발송되지 않습니다.
  • 은행 점검 시간대(23:30~00:35) 사이에는 환불이 실패할 수 있으니 해당 시간대는 피해서 환불 요청해주시기 바랍니다.
  • 테스트 환경에서는 개인정보 보호를 위하여 가상의 계좌번호 및 예금주명을 사용해주시기 바랍니다.
  • 부분 환불이 가능하며, 취소회차(cnclOrd)를 순차적으로 증가시켜 요청합니다.

요청 파라미터

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

params 객체

└mchtIdAN(10)영문+숫자, 최대 10byte*
헥토파이낸셜에서 부여하는 고유 상점아이디
nx_mid_il: 가상계좌 테스트
└verAN(4)영문+숫자, 최대 4byte*
전문의 버전
*고정값
└methodA(2)영문, 최대 2byte*
결제수단
*고정값 (VA: 가상계좌)
└bizTypeAN(2)영문+숫자, 최대 2byte*
업무 구분코드
*고정값 (C0: 환불)
└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(200)영문+숫자, 최대 200byte*SHA-256(실시간 생성)
SHA256 방식으로 생성한 해쉬값
NOTE

해쉬 생성 조합

trdDt + trdTm + mchtId + mchtTrdNo + cnclAmt(평문) + hashKey
└orgTrdNoAN(40)영문+숫자, 최대 40byte*
채번요청시 헥토파이낸셜에서 발급한 거래번호
*고정식 무제한(acntType=3) 방식은 채번 시 거래번호가 아니라, 입금 완료 노티(bizType: B1)로 수신한 거래번호(trdNo)를 사용합니다.
└crcCdA(3)영문, 최대 3byte*
통화 구분 값
*고정값
└cnclOrdN(3)숫자, 최대 3byte*
취소회차 (001부터 시작, 부분취소 2회차의 경우 002)
└taxTypeCdA(1)영문, 최대 1byte
면세여부 (복합과세인 경우 필수)
N: 과세 Y: 면세 G: 복합과세
└cnclAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding + Base64
환불금액
└taxAmtN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
환불금액 중 과세금액 (복합과세인 경우 필수)
└vatAmtN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
환불금액 중 부가세금액 (복합과세인 경우 필수)
└taxFreeAmtN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding + Base64
환불금액 중 면세금액 (복합과세인 경우 필수)
└refundBankCdAN(3)영문+숫자, 최대 3byte*
환불할 은행 코드
*가상계좌 은행 코드 목록 참고
└refundAcntNoN(16)숫자, 최대 16byte*AES-256AES-256/ECB/PKCS5Padding + Base64
환불할 계좌번호
└refundDpstrNmAHN(50)영문+한글+숫자, 최대 50byte*
환불계좌 예금주명
└cnclRsnAHN(255)영문+한글+숫자, 최대 255byte
환불사유 내용

응답 파라미터

타입 표기법
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*C0
업무 구분코드
└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
결과코드
└outRsltMsgAHN(200)영문+한글+숫자, 최대 200byte*정상적으로 처리되었습니다.
결과메시지

data 객체

└pktHashAN(64)영문+숫자, 최대 64byte*f395b6725a9a18...
요청시 hash 값 그대로 return
└orgTrdNoAN(40)영문+숫자, 최대 40byte*STFP_PGVAnx_mid_il00210806075210M1853381
채번 요청시 헥토파이낸셜에서 발급한 거래번호
└cnclAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding1000
환불금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└blcAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding0
환불성공시 거래번호 기준 남은 환불 가능잔액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.

노티 전문 (헥토파이낸셜 → 가맹점)

환불 완료 시 헥토파이낸셜에서 가맹점으로 노티(결과통보)가 전송됩니다.

노티 파라미터

└outStatCdAN(4)영문+숫자, 최대 4byte*0021
거래상태
0021: 성공
└trdNoAN(40)영문+숫자, 최대 40byte*STFP_PGVAnx_mid_il0211129135810M1494620
헥토파이낸셜에서 부여하는 고유 거래번호
└methodA(2)영문, 최대 2byte*VA
결제수단
VA: 가상계좌
└bizTypeAN(2)영문+숫자, 최대 2byte*C0
업무구분
C0: 환불
└mchtIdAN(10)영문+숫자, 최대 10byte*nx_mid_il
상점아이디
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*ORDER20211231100000
상점주문번호
└trdDtmN(14)숫자, 최대 14byte*20211231100000
거래일시 (YYYYMMDDhhmmss)
└trdAmtN(12)숫자, 최대 12byte1000
거래금액
└orgTrdNoAN(40)영문+숫자, 최대 40byteSTFP_PGVAnx_mid_il0211129135810M1494620
원거래번호
└orgTrdDtN(8)숫자, 최대 8byte20211231
원거래일자
└cnclTypeN(2)숫자, 최대 2byte00
취소거래타입
00: 전체취소 10: 부분취소
└pktHashAN(64)영문+숫자, 최대 64byte*a2d6d597d55d7c9b...
해쉬값 (거래상태코드+거래일자+거래시간+상점아이디+상점주문번호+거래금액+해쉬키)

노티 응답

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

응답설명
"OK"성공시 (대문자)
"FAIL"실패시 (대문자, FAIL로 응답시 노티가 재전송됩니다)
그 외비정상 실패로 인식하여, 설정된 횟수만큼 노티 재발송 처리함
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?