결제 취소

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

참고

에스크로 승인거래에 대한 취소는 에스크로 상태변경 참조 바랍니다.

요청

요청 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	✅	변경구분 코드
amount	Number			취소금액 부분취소 시 필수
remainAmount	Number			취소가능금액 부분취소 시 취소 가능잔액 검증용
clientIp	String	20Byte		요청자 IP
clientId	String	32Byte		요청자 ID 가맹점 관리자 로그인용 ID
cancelReqDate	String	8Byte	✅	취소 요청일자(yyyyMMdd)
msgAuthValue	String	200Byte	✅	요청값의 무결성을 검증 (메시지 인증값 바로가기)
reviseMessage	String	100Byte		취소사유
taxInfo	Object			복합과세 정보(복합과세 사용 시 필수) 아래 taxInfo 참조
basketUsed	String	1Byte		다중정산 장바구니 결제여부(Y/N)
basketInfo	Object			장바구니 정보(다중정산 사용 시 필수) 아래 basketInfo 참조

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": "고객 변심"
}

응답

파라미터

필드명	타입	길이	설명
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)
multiCardAmount	String	12Byte	페이코 카드 취소금액
multiPntAmount	String	12Byte	페이코 포인트 취소금액
multiCponAmount	String	12Byte	페이코 쿠폰 취소금액
reviseInfo	Object		취소(환불)응답 정보 아래 reviseInfo 참조

reviseInfo(취소응답 정보)

필드명	타입	길이	설명
payMethodTypeCode	String	2Byte	결제수단 코드 (결제수단 코드 참고)
approvalNo	String	50Byte	승인번호
approvalDate	String	14Byte	취소일시(yyyyMMddHHmmss)
cardInfo	Object		신용카드 취소 상세정보 아래 cardInfo 참조
cashReceiptInfo	Object		현금영수증 취소 상세정보 아래 cashReceiptInfo 참조

reviseInfo > cardInfo(신용카드 취소 상세정보)

필드명	타입	길이	설명
couponAmount	Number		즉시할인 취소금액

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": "TS02",
   "statusMessage": "승인취소",
   "reviseInfo": {
      "payMethodTypeCode": "11",
      "approvalNo": "00017177",
      "approvalDate": "20210326090200",
      "cardInfo": {
         "couponAmount": 0
      }
   }
}

변경 구분 코드(reviseTypeCode)

코드	서비스명	설명
20	매입	수동매입 가맹점 매입처리
32	부분취소	신용카드(간편결제 포함) 부분취소
33	부분취소	계좌이체, 휴대폰 결제거래 부분취소
40	전체 취소	결제 승인거래(가상계좌 채번취소 포함)를 전체 취소
51	현금영수증 취소	현금영수증 단독거래 취소
52	현금영수증 부분취소	현금영수증 단독거래 부분취소

메시지 인증값

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

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