헥토파이낸셜 개발자센터

현금영수증 재처리 등록 API

국세청 발급 오류 건에 대해 재처리를 등록하는 API입니다.

주의사항

자동재처리 가맹점

  • 영업담당자를 통해 자동재처리 가맹점으로 등록할 수 있습니다.
  • 국세청 오류코드에 따라 헥토파이낸셜에서 자동으로 재처리됩니다.
  • 자동재처리 시 자진발급번호로 발급됩니다.
  • 취소건 재처리는 원승인거래 등록번호로 발급됩니다.

자동재처리 가맹점이 아닌 경우

  • 오류내역 수신 시 재처리 API를 직접 호출해야 합니다.
  • API를 통해 재처리 요청한 거래는 승인번호와 발급일자가 신규 채번됩니다.

발급오류내역의 원거래 값을 사용하세요

reTrDt와 reAuthNo에는 재처리하려는 오류 거래의 발급일자와 승인번호를 입력합니다. 발급오류내역 조회 결과의 거래일시·승인번호와 가맹점에 보관한 원거래 정보를 대조한 뒤 요청하세요.
NOTE

승인번호 채번 기준

자동재처리 건은 발급일자가 국세청 등록 가능 기한(영업일 기준 3일전) 이내이면 최초 발급된 승인번호·발급일자로 재처리되고, 기한 초과 시 신규 채번됩니다. 반면 이 API로 직접 재처리 요청한 거래는 영업일 기준과 관계없이 항상 승인번호·발급일자가 신규 채번됩니다.

취소 재처리 시 주의사항

취소 재처리 시 identityGb, identity는 빈 값으로 전달하면 원거래 정보로 취소됩니다. 부분취소 시에도 동일하게 빈 값으로 전달하고 취소 금액만 계산하여 전달합니다.

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

등록 재처리 요청 파라미터

기본 등록 API 파라미터에 재처리 관련 필드를 추가합니다.

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

취소 재처리 요청 파라미터

취소건 재처리 시 등록 재처리와 동일한 기본 파라미터에 아래 추가 파라미터를 함께 전송합니다.

└assortA(1)영문, 최대 1byte*
승인구분
1: 취소
└authNoAN(9)영문+숫자, 최대 9byte*
원거래 승인번호
└orgTrDtAN(14)영문+숫자, 최대 14byte*
원거래 승인일시 (yyyyMMddHHmmss)
└reYnA(1)영문, 최대 1byte*
재처리여부
Y: 재처리요청
└reTrDtN(8)숫자, 최대 8byte*
재처리 원거래 발급일자 (yyyyMMdd)
*재처리할 오류 거래의 발급일자 입력
└reAuthNoAN(9)영문+숫자, 최대 9byte*
재처리 원거래 승인번호
*재처리할 오류 거래의 승인번호 입력

응답 파라미터

타입 표기법
N숫자A영문H한글AN영문+숫자AHN영문+한글+숫자
예: AN(10) = 영문+숫자, 최대 10byte
└resultCdAN(4)영문+숫자, 최대 4byte*0000
응답코드
0000: 성공
└resultMsgAHN(100)영문+한글+숫자, 최대 100byte*현금영수증 등록이 성공하였습니다.
응답메시지
└trTimeN(14)숫자, 최대 14byte*20180401001200
발급일시
*등록 재처리는 trDt 값, 취소 재처리는 API 요청일시가 반환됩니다. 가맹점에서 관리해야 합니다.
└authNoAN(9)영문+숫자, 최대 9byte*F62624676
승인번호 (신규 채번)
*가맹점 관리 필요

등록 재처리 요청 예시

https://tcash.settlebank.co.kr/pgtrans/CashReceiptMultiAction.do?_method=insertReceiptInfo
&mid=mid_test
&assort=0
&transNo=test115
&ordNm=테스트
&trDt=20180401001200
&taxYn=N
&amt=10000
&vat=1000
&svcAmt=0
&bizRegNo=0001112222
&purpose=0
&identityGb=4
&identity=0100001234
&deductionType=
&reYn=Y
&reTrDt=20180401
&reAuthNo=F62624672

취소 재처리 요청 예시

https://tcash.settlebank.co.kr/pgtrans/CashReceiptMultiAction.do?_method=insertReceiptInfo
&mid=mid_test
&assort=1
&transNo=CA20210316144124
&trDt=20210316144124
&taxYn=N
&amt=9090
&vat=910
&svcAmt=0
&purpose=0
&identityGb=
&identity=
&deductionType=
&authNo=F67198300
&orgTrDt=20210316144106
&reYn=Y
&reTrDt=20210316
&reAuthNo=F62624672

응답 예시

성공

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

실패

{
  "trTime": "",
  "resultCd": "1118",
  "authNo": "",
  "resultMsg": "재처리를 위한 원거래 정보가 없습니다."
}

재처리 관련 오류코드

코드메시지설명
1118재처리를 위한 원거래 정보가 없습니다.원거래 없음
1119자동재처리 대상 건입니다.자동재처리 대상
1120이미 재처리 요청된 내역이 있습니다.중복 재처리 요청
1121parameter 확인이 필요합니다.파라미터 오류
❓

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?