빌링 취소 API

빌키로 승인된 결제 건을 취소하는 API입니다.

요청 파라미터

POST

/api/v1/bill_cancel

Base URLhttps://dev.firstpay.co.kr

Content-Typeapplication/json

필수

조건부 필수

key	타입	최대크기	필수	설명
`mxId`	String	12		가맹점 ID
`mxIssueNo`	String	32		주문번호
`mxIssueDate`	String	14		주문일시 (YYYYMMDDHHMMSS)
`amount`	Number	-		결제금액 (취소할 금액)
`taxAmount`	Number	-	-	과세결제금액
`taxFreeAmount`	Number	-	-	면세결제금액
`callHash`	String	-		체크용 해시 데이터 : SHA256(mxId + mxIssueNo + amount + passKey)

안내사항

취소 요청 시 승인 시 사용한 mxIssueNo와 mxIssueDate를 정확히 입력해야 합니다.
특히, mxIssueDate 는 취소 요청 일시가 아닌 주문 당시 일시를 입력해야 합니다.

요청 예시

json

{
  "mxId": "testcorp",
  "mxIssueNo": "YYYYMMDD00001",
  "mxIssueDate": "YYYYMMDDHHMMSS",
  "amount": 1000,
  "callHash": "SHA256(mxId + mxIssueNo + amount + passKey)"
}

응답 파라미터

API 응답은 서비스 API 공통 형식을 따릅니다. data 필드 상세는 아래와 같습니다.

필수

조건부 필수

key	타입	최대크기	필수	설명
`mxId`	String	12		가맹점 ID
`mxIssueNo`	String	32		주문번호
`mxIssueDate`	String	14		주문일시 (YYYYMMDDHHMMSS)
`amount`	Number	12		결제금액
`authNo`	String	12	-	승인번호
	String	2	-	매입사코드
`acqName`	String	-	-	매입사명
	String	2	-	발급사코드
`issName`	String	-	-	발급사명
`ccNo`	String	-	-	마스킹 된 카드번호
	String	1	-	체크카드 여부
`authDate`	String	14	-	거래시간 (YYYYMMDDHHMMSS)
`tid`	String	40		거래 ID
`oTid`	String	40		원거래 ID

부분 취소

amount에 승인 금액보다 낮은 금액을 입력하면 부분 취소가 처리됩니다. 취소 금액의 합계는 승인 금액을 초과할 수 없습니다.

당일 취소 vs 익일 이후 취소

당일 취소: 승인 취소 (매출 발생 안 함)
익일 이후 취소: 매출 취소 (환불 처리)

일반적으로 승인 당일 자정(00시) 이전까지는 당일 취소로 처리됩니다.