헥토파이낸셜 개발자센터

010가상계좌 환불 API

입금 완료된 010가상계좌 거래를 환불하는 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

주의 사항

환불 서비스 등록 필수

환불 기능은 환불서비스가 등록된 상점에 한해 가능합니다. 환불 서비스 등록은 영업 담당자에게 문의하세요.
NOTE

테스트 환경 제한

테스트 환경에서는 실제 예금주명과 계좌번호로 환불 요청 시 오류가 발생합니다. 환불 테스트는 상용 환경에서 진행해 주세요.

요청 파라미터

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

params 객체

└mchtIdAN(10)영문+숫자, 최대 10byte*
헥토파이낸셜에서 부여하는 고유 상점아이디
└verAN(4)영문+숫자, 최대 4byte*
전문 버전
└methodA(2)영문, 최대 2byte*
결제수단
└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(64)영문+숫자, 최대 64byte*SHA-256(실시간 생성)
SHA256 방식으로 생성한 해쉬값
*환불요청일자 + 환불요청시간 + 상점아이디 + 상점주문번호 + 환불금액(평문) + 해쉬키
└orgTrdNoAN(40)영문+숫자, 최대 40byte*
채번시 헥토파이낸셜에서 발급한 거래번호
└crcCdA(3)영문, 최대 3byte*
통화구분
└cnclOrdN(3)숫자, 최대 3byte*
취소회차 (001부터 시작, 부분취소 2회차는 002)
└taxTypeCdA(1)영문, 최대 1byte
면세여부. 공백시 상점 기본 정보에 따름
Y: 면세 N: 과세 G: 복합과세
└cnclAmtN(9)숫자, 최대 9byte*AES-256AES-256/ECB/PKCS5Padding + Base64
환불금액
└taxAmtN(9)숫자, 최대 9byteAES-256AES-256/ECB/PKCS5Padding + Base64
환불금액 중 과세금액 (복합과세인 경우 필수)
└vatAmtN(9)숫자, 최대 9byteAES-256AES-256/ECB/PKCS5Padding + Base64
환불금액 중 부가세금액 (복합과세인 경우 필수)
└taxFreeAmtN(9)숫자, 최대 9byteAES-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*nxva_sb_il
상점아이디
└verAN(4)영문+숫자, 최대 4byte*0A18
전문 버전
└methodA(2)영문, 최대 2byte*VA
결제수단
└bizTypeAN(2)영문+숫자, 최대 2byte*C0
업무 구분코드
└encCdN(2)숫자, 최대 2byte*23
암호화 구분 코드
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*REFUND20211231100000
상점주문번호
└trdNoAN(40)영문+숫자, 최대 40byte*STBK_0123456789
헥토파이낸셜 거래번호
└trdDtN(8)숫자, 최대 8byte*20211231
환불요청일자
└trdTmN(6)숫자, 최대 6byte*120000
환불요청시간
└outStatCdAN(4)영문+숫자, 최대 4byte*0021
거래상태코드
0021: 성공 0031: 실패
└outRsltCdAN(4)영문+숫자, 최대 4byte*0000
결과코드 (0000인 경우 정상)
└outRsltMsgAHN(200)영문+한글+숫자, 최대 200byte*정상적으로 처리되었습니다.
결과메세지

data 객체

└pktHashAN(64)영문+숫자, 최대 64byte*75ac014c33165f3ee0c331123a0049f37a6e1578f8cec1d3d0374ffb75f18496
응답 해쉬값
└orgTrdNoAN(40)영문+숫자, 최대 40byteSTBK_0123456789
원거래번호
└cnclAmtN(9)숫자, 최대 9byteAES-256AES-256/ECB/PKCS5Padding1000
환불금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└blcAmtN(12)숫자, 최대 12byteAES-256AES-256/ECB/PKCS5Padding0
환불 후 남은 취소 가능 잔액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.

요청 예시

{
  "params": {
    "mchtId": "nxva_sb_il",
    "ver": "0A18",
    "method": "VA",
    "bizType": "C0",
    "encCd": "23",
    "mchtTrdNo": "REFUND20211231100000",
    "trdDt": "20211231",
    "trdTm": "120000",
    "mobileYn": "N",
    "osType": "W"
  },
  "data": {
    "pktHash": "해시값",
    "orgTrdNo": "STBK_0123456789",
    "crcCd": "KRW",
    "cnclOrd": "001",
    "taxTypeCd": "N",
    "cnclAmt": "AES암호화된환불금액",
    "refundBankCd": "011",
    "refundAcntNo": "AES암호화된계좌번호",
    "refundDpstrNm": "홍길동"
  }
}

응답 예시

성공

{
  "params": {
    "mchtId": "nxva_sb_il",
    "ver": "0A18",
    "method": "VA",
    "bizType": "C0",
    "encCd": "23",
    "mchtTrdNo": "REFUND20211231100000",
    "trdNo": "STBK_0123456791",
    "trdDt": "20211231",
    "trdTm": "120000",
    "outStatCd": "0021",
    "outRsltCd": "0000",
    "outRsltMsg": "정상적으로 처리되었습니다."
  },
  "data": {
    "pktHash": "응답해시값",
    "orgTrdNo": "STBK_0123456789",
    "cnclAmt": "AES암호화된환불금액",
    "blcAmt": "AES암호화된잔액"
  }
}

실패

{
  "params": {
    "mchtId": "nxva_sb_il",
    "ver": "0A18",
    "method": "VA",
    "bizType": "C0",
    "encCd": "23",
    "mchtTrdNo": "REFUND20211231100000",
    "trdNo": "",
    "trdDt": "20211231",
    "trdTm": "120000",
    "outStatCd": "0031",
    "outRsltCd": "0005",
    "outRsltMsg": "환불서비스가 등록되지 않은 상점입니다."
  },
  "data": {}
}
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?