환불 요청

취소 처리로 불가한 경우 당사 환불서비스 이용 시 환불 API 사용이 가능합니다.

환불 대상

다음 경우에 환불 API를 사용할 수 있습니다:

가상계좌 결제 건
계좌이체 결제 건
휴대폰 결제 건 (결제 당월 이후 취소 시)

환불 요청 전 확인사항

승인 요청 시 사용한 요청 파라미터와 동일한 mxId, mxIssueNo, mxIssueDate를 사용해야 합니다.
응답의 code는 통신 성공 여부를 의미하며, 실제 환불 결과는 data.replyCode로 확인해야 합니다.
replyCode가 0000이면 환불 성공, 그 외 값은 환불 실패입니다.

요청 파라미터

POST

/refund

Base URLhttps://dev.firstpay.co.kr

Content-Typeapplication/json

필수

조건부 필수

key	타입	최대크기	필수	설명
	String	2		결제종류
`mxId`	String	12		가맹점 ID
`mxIssueNo`	String	32		주문번호
`mxIssueDate`	String	14		주문일시 (YYYYMMDDHHMMSS)
`amount`	Number	12		결제금액 (결제한 금액보다 낮은 금액 입력 시 부분취소 처리)
`taxAmount`	Number	-	-	과세결제금액
`taxFreeAmount`	Number	-	-	면세결제금액
`subOrderNo`	String	12	-	서브주문번호 (부분취소 사용 시에만 Unique한 값 입력)
`callHash`	String	-		체크용 해시 데이터 : SHA256(mxId + mxIssueNo + amount + passKey)
`tid`	String	40	-	거래 ID
	String	3		환불은행코드
`holderName`	String	20		환불예금주명
`refundAccount`	String	16		환불계좌번호
`refundNotice`	String	256	-	환불 사유

필수 정보

환불 요청 시 다음 정보가 반드시 필요합니다:

refundBankCode: 환불받을 은행코드
holderName: 환불받을 계좌의 예금주명
refundAccount: 환불받을 계좌번호

부분 환불

amount에 결제한 금액보다 낮은 금액을 입력하면 부분 환불 처리가 처리됩니다. 이 경우 subOrderNo에 Unique한 서브주문번호를 반드시 입력해야 합니다.

요청 예시

json

{
  "payMethod": "VA",
  "mxId": "testcorp",
  "mxIssueNo": "YYYYMMDD00001",
  "mxIssueDate": "YYYYMMDDHHMMSS",
  "amount": 1000,
  "refundBankCode": "011",
  "holderName": "예금주명",
  "refundAccount": "3021111222233",
  "callHash": "SHA256(mxId + mxIssueNo + amount + passKey)"
}

응답 파라미터

API 응답은 서비스 API 공통 형식을 따릅니다. data 필드 상세는 아래와 같습니다.

응답 구조

code 필드는 통신 성공 여부를 의미합니다.
결제수단 전용 필드는 기관사에서 전달하지 않으면 빈 값일 수 있습니다.
기관사(카드사 등) 요청 후 승인 실패 시 data 내 replyCode를 반드시 확인해야 합니다.

공통

필수

조건부 필수

key	타입	최대크기	필수	설명
	String	2		결제종류
`mxId`	String	12		가맹점 ID
`mxIssueNo`	String	32		주문번호
`mxIssueDate`	String	14		주문일시 (YYYYMMDDHHMMSS)
`amount`	Number	12		결제금액
`replyCode`	String	8		에러코드 (성공: 0000)
`replyMessage`	String	-	-	에러메세지
`subOrderNo`	String	32	-	서브주문번호
`tid`	String	40		거래 ID
`oTid`	String	40		원거래 ID
`authDate`	String	14	-	거래시간 (YYYYMMDDHHMMSS)

계좌이체/가상계좌 전용

필수

조건부 필수

key	타입	최대크기	필수	설명
`escrowYn`	String	1	-	에스크로 결제 여부
`escrowCustNo`	String	17	-	에스크로 회원번호

휴대폰 전용

필수

조건부 필수

key	타입	최대크기	필수	설명
`cap`	String	6	-	사용가능한 소액금액

취소 vs 환불

취소 요청: 일반적인 결제 취소 (신용카드, 계좌이체 당월 등)
환불 요청: 취소가 불가능한 경우 (입금 완료된 가상계좌, 휴대폰 당월 이후 등)