헥토파이낸셜 개발자센터

휴대폰결제 환불 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

주의 사항

NOTE

서비스 신청 필수

휴대폰결제 환불 서비스를 이용하려면 사전에 서비스 등록이 필요합니다. 헥토파이낸셜 영업 담당자를 통해 환불 서비스 신청을 진행해 주세요.

휴대폰결제 환불 주의사항

환불은 결제 익월부터 사용합니다. 고객 계좌로 환불금액을 이체하는 방식입니다.
  • 당월 취소: 취소 API 사용
  • 익월 이후: 환불 API 사용 (예: 2023-06-30 승인 건은 2023-07-01부터 환불 API 요청)
  • 환불 시 고객의 환불 계좌 정보가 필요합니다.
  • 부분 환불: 취소 회차(cnclOrd)를 순차적으로 증가시켜 요청합니다.

요청 파라미터

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

params 객체

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

해쉬 생성 조합

trdDt + trdTm + mchtId + mchtTrdNo + cnclAmt(평문) + hashKey
└orgTrdNoAN(40)영문+숫자, 최대 40byte*
결제 시 헥토파이낸셜에서 발급한 거래번호
└crcCdA(3)영문, 최대 3byte*
통화 구분 값
*고정값
└cnclOrdN(3)숫자, 최대 3byte*
취소회차 (001부터 시작, 부분환불 2회차의 경우 002)
└cnclAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding + Base64
환불금액
└taxTypeCdA(1)영문, 최대 1byte
면세여부
N: 과세 Y: 면세 G: 복합과세
└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*nxhp_sb_il
상점아이디
└verAN(4)영문+숫자, 최대 4byte*0A19
전문의 버전
└methodA(2)영문, 최대 2byte*MP
결제수단
└bizTypeAN(2)영문+숫자, 최대 2byte*C1
업무 구분코드
└encCdN(2)숫자, 최대 2byte*23
암호화 구분 코드
└mchtTrdNoAN(100)영문+숫자, 최대 100byte*REFUND20211231100000
환불시 상점에서 생성한 주문번호
└trdNoAN(40)영문+숫자, 최대 40byte*STFP_PGMPnxhp_sb_il0211129135810M1494620
헥토파이낸셜 거래번호
└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_PGMPnxhp_sb_il0211129135810M1494620
결제 시 헥토파이낸셜에서 발급한 거래번호
└cnclAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding1000
환불금액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
└blcAmtN(12)숫자, 최대 12byte*AES-256AES-256/ECB/PKCS5Padding0
환불성공시 거래번호 기준 남은 환불 가능잔액
*실제 응답값은 AES-256 암호화된 값입니다. 복호화 후 사용하세요.
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?