헥토파이낸셜 개발자센터

자금반환청구 요청 API

가맹점 서버에서 헥토파이낸셜 서버로 착오송금으로 인한 자금반환청구를 요청합니다.

'송금' API의 결과 값인 거래번호(trdNo)를 사용하여 자금반환청구를 진행합니다.

API 정보

POST/v2/api/fundsReturn/req
Content-Typeapplication/json
테스트https://tbnpay.settlebank.co.kr/v2/api/fundsReturn/req
운영https://npay.settlebank.co.kr/v2/api/fundsReturn/req

요청 파라미터

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└hdInfoAN(50)영문+숫자, 최대 50byte*
전문정보 코드
*고정값
└mchtIdAN(8)영문+숫자, 최대 8byte*
헥토파이낸셜에서 부여하는 고유 상점아이디
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*
상점주문번호
*한글제외. 원거래에 대한 번호가 아닌 자금반환청구 요청의 주문번호
└ornTrdDtAN(8)영문+숫자, 최대 8byte*
원거래일자
*자금반환청구 거래의 거래일자. YYYYMMDD
└ornTrdNoAN(40)영문+숫자, 최대 40byte*
원거래번호
*자금반환청구할 거래번호
└wdBankCdAN(3)영문+숫자, 최대 3byte
출금은행코드
*출금한 은행의 은행코드 3자리
└wdAcntNoAN(24)영문+숫자, 최대 24byteAES-256AES-256/ECB/PKCS5Padding + Base64 (Standard)
출금계좌번호
*출금한 은행의 계좌번호
└dpBankCdAN(3)영문+숫자, 최대 3byte*
입금은행코드
*입금한 은행의 은행코드 3자리. 원거래 검증시 사용
└dpAcntNoAN(24)영문+숫자, 최대 24byte*AES-256AES-256/ECB/PKCS5Padding + Base64 (Standard)
입금계좌번호
*입금한 은행의 계좌번호. 원거래 검증시 사용
└trdAmtN(13)숫자, 최대 13byte*AES-256AES-256/ECB/PKCS5Padding + Base64 (Standard)
거래금액(청구금액)
*자금반환 청구할 금액. 원거래 금액과 같으면 전액 반환, 원거래 금액보다 적으면 부분 반환
└rtnAcntNoAN(24)영문+숫자, 최대 24byteAES-256AES-256/ECB/PKCS5Padding + Base64 (Standard)
반환계좌번호
*반환금액을 받을 계좌번호
└rtnRsnCdAN(2)영문+숫자, 최대 2byte*
반환사유코드
02: 계좌입력오류 03: 금액입력오류 04: 이중입금 05: 기타 08: 고객반환의사표시
*자금반환청구 요청 사유 코드
└rtnRsnMsgAN(100)영문+숫자, 최대 100byte*
반환사유 메시지
*자금반환청구 요청 사유
└cphoneNoAN(3)영문+숫자, 최대 3byte*AES-256AES-256/ECB/PKCS5Padding + Base64 (Standard)
담당자 전화번호
└emailAN(100)영문+숫자, 최대 100byte*AES-256AES-256/ECB/PKCS5Padding + Base64 (Standard)
담당자 이메일
└custIpAN(15)영문+숫자, 최대 15byte
고객 IP 주소
*가맹점 서버의 IP가 아닌 고객 기기의 IP 주소
└pktHashAN(200)영문+숫자, 최대 200byte*SHA-256(실시간 생성)
SHA256 방식으로 생성한 해쉬값
*상점아이디 + 원거래일자 + 원거래번호 + 입금은행코드 + 입금계좌번호(평문) + 거래금액(평문) + 반환사유코드 + 담당자 전화번호(평문) + 이메일(평문) + 인증키

요청 전문 해쉬 코드

항목조합 필드
pktHash 값상점아이디 + 원거래일자 + 원거래번호 + 입금은행코드 + 입금계좌번호(평문) + 거래금액(평문) + 반환사유코드 + 담당자 전화번호(평문) + 이메일(평문) + 인증키

응답 파라미터

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└outStatCdAN(4)영문+숫자, 최대 4byte*
거래상태코드 (성공/실패)
0021: 성공 0031: 실패
└outRsltCdAN(4)영문+숫자, 최대 4byte*
거절코드
*거절코드 테이블 참조
└outRsltMsgAN(300)영문+숫자, 최대 300byte*정상처리되었습니다.
결과메시지
*오류가 발생시 오류에 대한 메시지 전달
└trdNoAN(40)영문+숫자, 최대 40byte*STFP_FIRM20230330095423555
헥토파이낸셜 거래번호
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*OID20230330095512450
상점 주문번호
*한글제외

요청 예시

{
  "hdInfo": "SPAY_FR0W_1.0",
  "mchtId": "midtest",
  "mchtTrdNo": "OID201902210001",
  "ornTrdDt": "20230330",
  "ornTrdNo": "STFP_FIRM1233444365430698",
  "wdBankCd": "004",
  "wdAcntNo": "AES암호화된출금계좌번호",
  "dpBankCd": "020",
  "dpAcntNo": "AES암호화된입금계좌번호",
  "trdAmt": "AES암호화된거래금액",
  "rtnAcntNo": "AES암호화된반환계좌번호",
  "rtnRsnCd": "05",
  "rtnRsnMsg": "착오송금으로 인한 반환 요청",
  "cphoneNo": "AES암호화된전화번호",
  "email": "AES암호화된이메일",
  "custIp": "127.0.0.1",
  "pktHash": "해시값"
}

응답 예시

{
  "outStatCd": "0021",
  "outRsltCd": "0000",
  "outRsltMsg": "정상처리되었습니다.",
  "trdNo": "STFP_FIRM20230330095423555",
  "mchtTrdNo": "OID20230330095512450"
}
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?