취소 요청

결제 성공 건 중 취소처리가 필요한 경우 호출합니다.

중요

입금 완료된 가상계좌 결제 건의 경우 취소가 불가합니다. 환불서비스 이용 시 환불 요청 API를 통해 처리 가능합니다.
결제수단별로 취소 가능일이 다릅니다. 결제수단별 정책 - 정책 요약을 확인해주세요.

취소 요청 전 확인사항

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

요청 파라미터

POST

/cancel

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	-		결제금액 (결제한 금액보다 낮은 금액 입력 시 부분취소 처리)
`taxAmount`	Number	-	-	과세결제금액
`taxFreeAmount`	Number	-	-	면세결제금액
`cancelNotice`	String	256	-	취소 사유
`subOrderNo`	String	12	-	서브주문번호 (부분취소 사용 시에만 Unique한 값 입력)
`callHash`	String	-		체크용 해시 데이터 : SHA256(mxId + mxIssueNo + amount + passKey)
`tid`	String	40	-	거래 ID
`netCancelFlag`	String	1	-	망취소 여부 (망취소 요청 시 "Y")

부분취소

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

망취소

승인 요청 응답을 수신하지 못했거나, 정상 응답 수신 후 내부 처리 실패 등 예외로 인해 취소 처리가 필요한 거래에 대해 netCancelFlag = Y로 설정하여 요청합니다.
해당 플래그가 설정되면 당사 시스템이 원거래를 확인한 뒤, 원거래가 존재하는 경우 즉시 정상 응답 후 내부 취소 처리를 진행합니다.

요청 예시

json

{
  "payMethod": "CC",
  "mxId": "testcorp",
  "mxIssueNo": "YYYYMMDD00001",
  "mxIssueDate": "YYYYMMDDHHMMSS",
  "amount": 1000,
  "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	12	-	서브주문번호
`tid`	String	40		거래 ID
`oTid`	String	40		원거래 ID
`authDate`	String	14	-	거래시간 (YYYYMMDDHHMMSS)

신용카드/간편결제 전용

필수

조건부 필수

key	타입	최대크기	필수	설명
`authNo`	String	12	-	승인번호
	String	2	-	매입사코드
`acqName`	String	-	-	매입사명
	String	2	-	발급사코드
`issName`	String	-	-	발급사명
	String	1	-	체크카드 여부
`ccNo`	String	-	-	마스킹 된 카드번호
`acqNo`	String	12	-	가맹점번호
`installment`	String	2	-	할부개월

계좌이체/가상계좌 전용

필수

조건부 필수

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

휴대폰 전용

필수

조건부 필수

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

취소가 불가능한 경우

취소 가능일이 지났거나, 입금 완료된 가상계좌 결제 건은 환불 요청 서비스를 이용하세요.