에스크로 상태변경

에스크로 상태 변경을 하는 API 입니다.

참고

• 에스크로 구매학인 및 구매거절 상태는 고객에게 발송되는 구매확정 메일을 통해 진행됩니다.
• 구매확정이나 구매거절이 완료되면 노티(웹훅) 서비스를 통해 결과가 전송됩니다.
• 구매거절 상태일 경우 KICC로 문의하여 주시기 바랍니다.
• 부분취소 및 부분환불을 지원하지 않습니다.

상태 다이어그램

요청

요청 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	✅	변경구분 에스크로 상태변경 시 "61"로 고정
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		취소사유
escrowInfo	Object			에스크로 정보(배송중 요청 시 필수) 아래 escrowInfo 참조
taxInfo	Object			복합과세 정보(복합과세 사용 시 필수) 아래 taxInfo 참조
refundInfo	Object			환불요청 정보(환불요청 시 필수) 아래 refundInfo 참조

escrowInfo(에스크로 정보)

필드명	타입	길이	필수여부	설명
deliveryCode	String	4Byte	✅	배송구분 자가배송: "DE01" 택배배송: "DE02"
deliveryCorpCode	String	4Byte	✅	배송사 코드 (택배사 코드 참고)
deliveryInvoice	String	30Byte	✅	송장번호

taxInfo(복합과세 정보)

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

refundInfo(환불요청 정보)

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

승인취소

요청 예시

{  
    "mallId": "{상점ID}", 
    "shopTransactionId": "{API 멱등성 키}", 
    "pgCno": "{PG 거래고유번호}",
    "reviseTypeCode": "61",
    "reviseSubTypeCode": "ES02",
    "cancelReqDate": "{요청 일자}",
    "msgAuthValue": "{메시지 인증값}"    
}

환불요청

요청 예시

{  
    "mallId": "{상점ID}", 
    "shopTransactionId": "{API 멱등성 키}", 
    "pgCno": "{PG 거래고유번호}",
    "reviseTypeCode": "61",
    "reviseSubTypeCode": "ES05",
    "cancelReqDate": "{요청 일자}",
    "msgAuthValue": "{메시지 인증값}",
    "refundInfo": {
        "refundBankCode": "008",
        "refundAccountNo": "1231231230",
        "refundDepositName": "환불계좌 예금주명"
    } 
}

배송중

요청 예시

{  
    "mallId": "{상점ID}", 
    "shopTransactionId": "{API 멱등성 키}", 
    "pgCno": "{PG 거래고유번호}",
    "reviseTypeCode": "61",
    "reviseSubTypeCode": "ES07",
    "cancelReqDate": "{요청 일자}",
    "msgAuthValue": "{메시지 인증값}",
    "escrowInfo": {
        "deliveryCode": "DE02",
        "deliveryCorpCode": "DC01",
        "deliveryInvoice": "12345678901234567890123456"
    } 
}

응답

에스크로 상태변경 응답의 경우 거래관리 API 가이드를 참조

변경 세부구분 코드(reviseSubTypeCode)

코드	서비스명	설명
ES02	승인취소	계좌이체 승인취소 또는 가상계좌 채번취소
ES05	환불요청	가상계좌 입금거래 환불요청
ES07	배송중	상품 배송 후 요청
ES08	배송중 취소요청	상품 배송 후 취소요청
ES09	배송중 취소완료	상품반품 완료 후 취소완료
ES10	배송중 환불요청	상품 배송 후 환불요청
ES11	배송중 환불완료	상품반품 완료 후 환불완료
ES14	구매확인 후 환불요청	구매확인 후 환불요청
ES15	구매확인 후 환불완료	상품반품 완료 후 환불완료
ES16	구매확인 후 취소요청	구매확인 후 취소요청
ES19	구매확인 후 취소완료	상품반품 완료 후 취소완료

택배사 코드

코드	택배사	코드	택배사
DC01	대한통운	DC02	CJGLS
DC03	SC로지스	DC04	옐로우캡
DC05	로젠택배	DC06	동부익스프레스
DC07	우체국	DC08	한진택배
DC09	현대택배	DC10	KGB택배
DC11	하나로택배	DC12	기타

메시지 인증값

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

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