결제 취소

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

참고

• 본 API는 PG 결제를 위해 제공되는 서비스 입니다.
• 에스크로 결제 거래는 에스크로 상태변경 참조 바랍니다.

요청

요청 URL

POST https://{API 도메인}/easypay/payment/cancel.do
Content-type: application/json; charset=euc-kr

참고

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

주의사항

• 응답 대기시간 초과 및 네트워크 오류로 응답을 받지 못한 경우 반드시 거래상태 조회를 통해 PG 거래고유번호를 조회 후 취소처리 바랍니다. 최종 결제 취소가 완료되기까지 시간이 걸리므로 timeout을 30초로 설정해야 합니다.

파라미터

필드명	타입	길이	필수여부	설명
mallId	String	8Byte	✅	KICC에서 부여한 가맹점ID
shopTransactionId	String	60Byte	✅	제휴사 거래고유번호 (API 멱등성 키)
shopOrderNo	String	40Byte	✅	결제승인 요청 시 사용했던 제휴사 주문번호
pgCno	String	20Byte	✅	원 거래 PG 거래고유번호
cancelTxtype	String	2Byte	✅	취소구분 전체취소: “40”, 부분취소: “32”
amount	Number			취소요청금액
remainAmount	Number			취소가능금액 취소가능 잔액검증
comTaxAmt	Number			취소금액 중 과세금액 복합과세 부분취소 시 사용
comFreeAmt	Number			취소금액 중 비과세 금액 복합과세 부분취소 시 사용
comVatAmt	Number			취소금액 중 부가세 금액 복합과세 부분취소 시 사용
msgAuthValue	String	200Byte	✅	요청값의 무결성을 검증 (메시지 인증값 바로가기)
cancelReqDate	String	8Byte	✅	취소요청일자(yyyyMMdd)

요청 예시

{  
    "mallId": "{KICC에서 부여한 가맹점ID}", 
    "shopTransactionId": "{API 멱등성 키}", 
    "pgCno": "{PG 거래고유번호}",
    "cancelTxtype": "40",
    "cancelReqDate": "{요청 일자}",
    "msgAuthValue": "{메시지 인증값}"
}

응답

파라미터

필드명	타입	길이	설명
resCd	String	4Byte	결과코드(정상 : “0000”)
resMsg	String	1000Byte	결과 메시지
shopTransactionId	String	60Byte	취소요청 시 전송한 값 그대로 사용
mallId	String	8Byte	KICC에서 부여한 가맹점ID
oriPgCno	String	20Byte	원 거래 PG 거래고유번호
cancelPgCno	String	20Byte	취소 PG 거래고유번호
shopOrderNo	String	40Byte	제휴사 주문번호
cancelAmount	Number		취소금액
remainAmount	Number		취소 후 잔액
transactionDate	String	14Byte	거래일시(yyyyMMddHHmmss)
statusCode	String	4Byte	거래상태 코드 (거래상태 코드 참고)
statusMessage	String	50Byte	거래상태 메시지
paymentInfo	Array		결제수단 취소상세 내역 (아래 paymentInfo 참조)

paymentInfo(결제수단 취소상세 내역)

필드명	타입	길이	설명
payMethodTypeCode	String	2Byte	결제수단 코드 (결제수단 코드 참고)
cancelAmount	Number		취소금액
remainAmount	Number		취소 후 잔액(요청 시 remainAmount 항목이 있을 시 응답)
couponAmount	Number		즉시할인 취소금액
cashReceiptInfo	Object		현금영수증 취소 상세정보 (아래 cashReceiptInfo 참조)

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": "승인취소",
   "paymentInfo": [
      {
         "payMethodTypeCode": "11",
         "cancelAmount": 5100
      }
   ]
}

메시지 인증값

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

pgCno(PG 거래고유번호) + “|” + shopTransactionId(제휴사 거래고유번호)