결제 환불

결제 완료된 거래 전체 또는 부분 환불 처리를 하는 API 입니다.

참고

• 에스크로 승인거래에 대한 취소는 에스크로 상태변경 참조 바랍니다.
• 환불 서비스의 경우 지결환불과 즉시환불 두가지 서비스가 제공되고 있으니, 서비스 신청 시 영업담당자와 협의하여 주시기 바랍니다.

실시간 환불

환불 요청 즉시 고객의 환불계좌로 실시간 환불 처리되는 서비스 입니다.

지결 환불

환불 요청 D+1에 고객의 환불계좌로 환불 처리되는 서비스 입니다. 환불완료 시 노티(웹훅)을 통해 처리결과를 받을 수 있습니다. 반드시 노티(웹훅) URL을 등록해야 합니다.

요청

요청 URL

POST https://{API 도메인}/api/trades/revise
Content-type: application/json; charset=utf-8

참고

API 멱등성 지원 대상 (API 멱등성 참조)

주의사항

최종 결제 취소가 완료되기까지 시간이 걸리므로 timeout을 30초로 설정해야 합니다.

파라미터

필드명	타입	길이	필수여부	설명
mallId	String	8Byte	✅	KICC에서 부여한 상점ID
shopTransactionId	String	60Byte	✅	상점 거래고유번호 (API 멱등성 키)
pgCno	String	20Byte	✅	원 거래 PG 거래고유번호
reviseTypeCode	String	2Byte	✅	변경구분 (변경 구분 코드표 바로가기) 지결 전체환불: “60” 지결 부분환불: “62”
reviseSubTypeCode	String	4Byte		변경 세부구분 (변경 세부구분 코드표 바로가기)
amount	Number			취소금액 부분환불 시 필수
remainAmount	Number			환불가능금액(환불 시 가능잔액 검증용)
clientIp	String	20Byte		요청자 IP
clientId	String	32Byte		요청자 ID 가맹점 관리자 로그인용 ID
cancelReqDate	String	8Byte	✅	취소 요청일자(yyyyMMdd)
msgAuthValue	String	200Byte	✅	요청값의 무결성을 검증 (메시지 인증값 바로가기)
reviseMessage	String	100Byte		환불사유
refundQueryFlag	String	1Byte		환불결과 조회플래그(‘Y’ : 조회) 즉시환불 타임아웃 발생 시 필수 환불응답이 “VTIM”, “VT00”일 경우 재요청 필요
refundInfo	Object		✅	환불요청 정보 아래 refundInfo 참조
taxInfo	Object			복합과세 정보(복합과세 사용 시 필수) 아래 taxInfo 참조
basketUsed	String	1Byte		다중정산 장바구니 결제여부(Y/N)
basketInfo	Object			장바구니 정보(다중정산 사용 시 필수) 아래 basketInfo 참조

refundInfo(환불요청 정보)

필드명	타입	길이	필수여부	설명
refundBankCode	String	3Byte	✅	환불계좌 은행코드 (은행 코드 참고)
refundAccountNo	String	14Byte	✅	환불계좌 계좌번호
refundDepositName	String	50Byte	✅	환불계좌 예금주명
depositPgCno	String	20Byte		입금거래번호(다회입금계좌 환불 시 필수)

taxInfo(복합과세 정보)

필드명	타입	길이	필수여부	설명
taxationAmount	Number		✅	취소 과세 금액
taxFreeAmount	Number		✅	취소 비과세 금액
vatAmount	Number		✅	취소 부가세 금액

basketInfo(장바구니 정보)

필드명	타입	길이	필수여부	설명
productPgCno	String	20Byte	✅	개별상품 PG 거래고유번호
sellerId	String	50Byte	✅	셀러ID

요청 예시

{
    "mallId": "{상점ID}", 
    "shopTransactionId": "{API 멱등성 키}", 
    "pgCno": "{PG 거래고유번호}",
    "reviseTypeCode": "40",
    "cancelReqDate": "{요청 일자}",
    "msgAuthValue": "{메시지 인증값}",
    "reviseMessage": "고객 변심",
    "refundInfo": {
        "refundBankCode": "003",
        "refundAccountNo": "{환불 계좌번호}",
        "refundDepositName": "홍길동",
        "depositPgCno": "{입금 거래번호}"
    }
}

응답

파라미터

필드명	타입	길이	설명
resCd	String	4Byte	결과코드(정상 : “0000”)
resMsg	String	1000Byte	결과 메시지
shopTransactionId	String	60Byte	취소요청 시 전송한 값 그대로 사용
mallId	String	8Byte	KICC에서 부여한 상점ID
oriPgCno	String	20Byte	원 거래 PG 거래고유번호
cancelPgCno	String	20Byte	환불 PG 거래고유번호
transactionDate	String	14Byte	거래일시(yyyyMMddHHmmss)
cancelAmount	Number		취소금액
remainAmount	Number		취소 후 잔액(요청 시 remainAmount 항목이 있을 시 응답)
statusCode	String	4Byte	거래상태 코드 (거래상태 코드 참고)
statusMessage	String	50Byte	거래상태 메시지
escrowUsed	String	1Byte	에스크로 사용여부(Y/N)
reviseInfo	Object		환불 응답 정보 아래 reviseInfo 참조

reviseInfo(환불응답 정보)

필드명	타입	길이	설명
payMethodTypeCode	String	2Byte	결제수단 코드 (결제수단 코드 참고)
approvalDate	String	14Byte	환불일시(yyyyMMddHHmmss)
refundInfo	Object		환불 상세정보 아래 refundInfo 참조
cashReceiptInfo	Object		현금영수증 취소상세정보 아래 cashReceiptInfo 참조

reviseInfo > refundInfo(환불 상세정보)

필드명	타입	길이	설명
refundDate	String	14Byte	환불예정일시(yyMMddHHmmss)
depositPgCno	String	20Byte	가상계좌 입금 거래번호(가상계좌일 경우 응답)

reviseInfo > cashReceiptInfo(현금영수증 취소 상세정보)

필드명	타입	길이	설명
resCd	String	4Byte	결과코드
resMsg	String	1000Byte	결과 메시지
approvalNo	String	50Byte	현금영수증 취소 승인번호
cancelDate	String	14Byte	현금영수증 취소일시(yyyyMMddHHmmss)

응답 예시

{
   "resCd": "0000",
   "resMsg": "정상취소",
   "mallId": "{요청한 상점ID}",
   "shopTransactionId": "{요청한 API 멱등성 키}",
   "oriPgCno": "{PG 거래고유번호}",
   "cancelPgCno": "{취소 PG 거래고유번호}",  
   "shopOrderNo": "{상점 주문번호}",
   "cancelAmount": "51004",
   "remainAmount": "0",
   "transactionDate": "20210326090200",
   "statusCode": "RF01",
   "statusMessage": "환불요청",
   "reviseInfo": {
      "payMethodTypeCode": "21",
      "approvalDate": "20210326090200",
      "refundInfo": {
         "refundDate": "20210326090200",
         "depositPgCno": "{입금 거래번호}"
      }
   }
}

변경 구분 코드(reviseTypeCode)

코드	서비스명	설명
60	지결 전체환불	가상계좌, 휴대폰 거래 환불
62	지결 부분환불	가상계좌, 휴대폰 거래 환불
63	실시간 환불	가상계좌, 휴대폰 거래 환불 전체/부분 환불 구분은 변경 세부구분 코드로 처리

변경 세부구분 코드(reviseSubTypeCode)

구분	코드	서비스명	설명
지결환불	RF01	환불요청	전체 또는 부분환불 모두 동일한 코드 적용
실시간 환불	10	전체환불(계좌인증)	KICC에서 계좌인증 후 환불
	11	부분환불(계좌인증)	KICC에서 계좌인증 후 환불
	20	전체환불(계좌미인증)	상점에서 계좌인증 후 환불
	21	부분환불(계좌미인증)	상점에서 계좌인증 후 환불

메시지 인증값

메시지 인증값 구성은 아래와 같이 조합하고 해당값을 HmacSHA256으로 해시한다. 메시지 인증 참조

pgCno(PG 거래고유번호) + “|” + shopTransactionId (상점 거래고유번호)