헥토파이낸셜 개발자센터

현금영수증 취소 API

국세청에 등록된 현금영수증을 취소하는 API입니다.

주의사항

  • 취소 시 주문번호(transNo)는 기존 주문번호와 다른 새로운 번호로 요청해야 합니다.
  • 부분 취소는 여러 번 가능하지만, 누적 취소금액이 원거래 금액을 초과할 수 없습니다. (예: 원거래 1,000원 등록 건을 같은 날짜에 1,000원씩 2번 취소하면 누적 취소금액이 2,000원으로 원거래를 초과하여 2건 모두 에러 처리)
  • 현금영수증 취소는 요청 익일(D+1) 00시에 국세청으로 일괄 전송됩니다.
  • 취소 결과는 D+1 13시 이후 발급오류내역 조회 API로 확인할 수 있습니다.

API 정보

GET/POST/pgtrans/CashReceiptMultiAction.do?_method=insertReceiptInfo
Content-Type
요청application/x-www-form-urlencoded;charset=UTF-8
응답text/plain;charset=UTF-8
테스트https://tcash.settlebank.co.kr/pgtrans/CashReceiptMultiAction.do?_method=insertReceiptInfo
운영https://cash.settlebank.co.kr/pgtrans/CashReceiptMultiAction.do?_method=insertReceiptInfo

요청 파라미터

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└midAN(10)영문+숫자, 최대 10byte*
상점아이디
*헥토파이낸셜에서 발급받은 가맹점 ID
└assortA(1)영문, 최대 1byte*
승인구분
1: 취소
└transNoAN(50)영문+숫자, 최대 50byte*
주문번호 (가맹점 고유번호)
*기존 주문번호가 아닌 새로 채번된 주문번호로 요청. 날짜와 상관없이 동일 고유번호 발생 시 오류처리
└ordNmAN(30)영문+숫자, 최대 30byte
주문자명
└trDtAN(14)영문+숫자, 최대 14byte*
거래일시 (yyyyMMddHHmmss)
└taxYnA(1)영문, 최대 1byte
과세구분
N: 과세 Y: 면세 G: 복합과세
*N(과세): amt에 취소할 과세금액, vat에 부가세 입력
Y(면세): amt에 취소할 면세금액, vat는 0으로 입력
G(복합과세): amt에 취소할 과세+면세금액, vat에 과세금액의 부가세 입력(vat 0원도 정상)
전체 취소 시 identityGb, identity를 빈 값으로 전달하면 원거래 승인번호와 원거래 승인일시의 현금영수증 발행 정보로 취소
부분 취소 시 identityGb, identity를 빈 값으로 전달하고 취소 금액을 계산하여 전달
취소 시 등록번호 구분, 등록번호, 과세구분, 공급가액, 부가세, 봉사료, 하위사업자번호, 용도구분은 요청값 그대로 국세청에 신고되므로, 원거래 기준으로 취소할 수 있도록 identityGb와 identity는 빈 값 전달 권장
└amtN(10)숫자, 최대 10byte*
취소 공급가액
*전체취소: 원거래 공급가액, 부분취소: 취소할 공급가액
└vatN(10)숫자, 최대 10byte*
취소 부가세
*전체취소: 원거래 부가세, 부분취소: 취소할 부가세
└svcAmtN(10)숫자, 최대 10byte
취소 봉사료
└bizRegNoN(10)숫자, 최대 10byte
하위사업자번호
└purposeA(1)영문, 최대 1byte
용도구분
0: 소득공제 1: 지출증빙
*자진발급번호로 요청 시 0(소득공제)으로 입력
취소 시 원거래 정보 사용을 위해 빈 값 전달 권장
└identityGbA(1)영문, 최대 1byte
현금영수증 등록번호 구분
1: 카드번호 (국세청 등록 카드) 2: 주민번호 3: 사업자번호 4: 휴대전화번호
*자진발급번호로 요청 시 4(휴대전화번호)로 입력
취소 시 빈 값으로 전달 권장 (원거래 정보로 자동 취소)
└identityN(18)숫자, 최대 18byte
현금영수증 등록번호
*등록 시의 현금영수증 등록번호와 동일해야 함
└deductionTypeA(1)영문, 최대 1byte
추가공제 구분
Y: 대중교통 C: 문화비(도서,공연비,체육시설) T: 전통시장 B: 전통시장내 도서공연비
*해당 추가공제 거래에만 입력
문화비 소득공제 제공 단일사업자는 값을 생략해도 문화비로 처리
전통시장/전통시장 내 문화비로 지정한 사업자번호가 국세청에 등록되지 않은 경우 일반 소득공제로 처리
2025/07/01 이후 체육시설 사용료(수영장, 헬스 등)도 문화비(C)에 포함: 강습료 50%, 입장료와 대여료(수건, 운동복) 100% 공제
└authNoAN(9)영문+숫자, 최대 9byte*
원거래 승인번호
*등록 시 받은 승인번호
└orgTrDtAN(14)영문+숫자, 최대 14byte*
원거래 승인일시 (yyyyMMddHHmmss)
*등록 시의 trDt 값

응답 파라미터

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└resultCdAN(4)영문+숫자, 최대 4byte*0000
응답코드
0000: 성공
└resultMsgAHN(100)영문+한글+숫자, 최대 100byte*현금영수증 등록이 성공하였습니다.
응답메시지
*현금영수증 등록이 성공하였습니다. (성공 시) / 오류 메시지 (실패 시, 예: 주문번호가 없습니다. - 1113)
└trTimeN(14)숫자, 최대 14byte*20210316144124
발급일시
*취소 시: API 요청일시
└authNoAN(9)영문+숫자, 최대 9byte*F67198300
승인번호
*취소한 현금영수증 승인번호

요청 예시

전체 취소 요청 (10,000원)

https://tcash.settlebank.co.kr/pgtrans/CashReceiptMultiAction.do?_method=insertReceiptInfo
&mid=mid_test
&assort=1
&transNo=CA20210316144124
&ordNm=
&trDt=20210316144124
&taxYn=N
&amt=9090
&vat=910
&svcAmt=
&bizRegNo=
&purpose=
&identityGb=
&identity=
&authNo=F67198300
&orgTrDt=20210316144106

부분 취소 요청 (5,000원)

https://tcash.settlebank.co.kr/pgtrans/CashReceiptMultiAction.do?_method=insertReceiptInfo
&mid=mid_test
&assort=1
&transNo=CA20210316144125
&ordNm=
&trDt=20210316144125
&taxYn=N
&amt=4545
&vat=455
&svcAmt=
&bizRegNo=
&purpose=
&identityGb=
&identity=
&authNo=F67198300
&orgTrDt=20210316144106

응답 예시

성공

{
  "trTime": "20210316144124",
  "resultCd": "0000",
  "authNo": "F67198300",
  "resultMsg": "현금영수증 등록이 성공하였습니다."
}

실패

{
  "trTime": "",
  "resultCd": "1114",
  "authNo": "",
  "resultMsg": "정상처리된 원거래가 존재하지 않습니다."
}

요청결과 코드

코드메시지설명
0000현금영수증 등록이 성공하였습니다.정상 취소
1000현금영수증 등록 서비스를 이용할 수 없습니다.현금영수증 가맹점이 아님
1010금액 정보가 잘못되었습니다.
카드번호를 확인해주세요.
주민번호를 확인해주세요.
사업자번호를 확인해주세요.
휴대전화번호를 확인해주세요.		금액 관련에만 금액정보가 잘못된 경우,
카드번호 유효성 오류,
주민번호 유효성 오류,
사업자번호 유효성 오류,
휴대전화번호 유효성 오류
1111Exception Message시스템 오류
1112주문번호가 없습니다.transNo가 빈값
1113동일 transNo/동일금액 취소 건이 존재합니다.중복 취소 요청
1114정상처리된 원거래가 존재하지 않습니다.취소 시 원거래 없음
1115기존 등록된 거래가 존재합니다.중복 등록 요청
1116원거래 금액보다 취소금액이 큽니다.취소금액 초과
1117필수정보가 누락되었습니다.필수 데이터 누락
1118재처리를 위한 원거래 정보가 없습니다.재처리 요청 시 원거래가 없는 경우
1119자동재처리 대상 건입니다.재처리 요청 거래가 자동재처리 대상일 경우
1120이미 재처리 요청된 내역이 있습니다.중복 재처리 요청
1121parameter 확인이 필요합니다.파라미터 오류
2000등록된 상점이 없습니다. ID를 확인해주세요.상점ID 오류
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?