헥토파이낸셜 개발자센터

현금영수증 등록 API

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

주의사항

API 등록 성공은 국세청 최종 발급 완료가 아닙니다

이 API는 현금영수증 등록 요청을 접수하고 승인번호를 발급합니다. 접수 내역은 익일(D+1) 국세청에 일괄 전송되므로, 응답의 resultCd가 0000이어도 익일 발급오류내역 또는 발급상태 조회 API로 최종 처리 결과를 확인해야 합니다.

과세금액 계산

총 거래금액 = 공급가액(amt) + 부가세(vat) + 봉사료(svcAmt). 과세 시 공급가액은 부가세보다 커야 합니다.
NOTE

응답값 보관

응답으로 받은 trTime과 authNo는 취소, 상태 조회, 오류 확인에 사용됩니다. 가맹점 시스템에 주문번호(transNo)와 함께 보관하세요.
  • 자진발급번호(0100001234)로 발급 시 고객이 홈택스에서 본인 명의로 변경할 수 있습니다.
  • 현금영수증은 요청 익일(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*
승인구분
0: 승인(등록)
└transNoAN(50)영문+숫자, 최대 50byte*
주문번호 (가맹점 고유번호)
*가맹점에서 관리하는 고유 주문번호. 날짜와 상관없이 동일 고유번호 발생 시 오류처리
└ordNmAN(30)영문+숫자, 최대 30byte
주문자명
└trDtAN(14)영문+숫자, 최대 14byte*
거래일시 (yyyyMMddHHmmss)
└taxYnA(1)영문, 최대 1byte
과세구분
N: 과세 Y: 면세 G: 복합과세 null: 가맹점 정보 기준 자동계산
*N(과세): amt에 과세금액, vat에 부가세 입력
Y(면세): amt에 면세금액, vat는 0 입력
G(복합과세): amt에 과세+면세금액, vat에 과세금액의 부가세 입력(vat 0원도 정상)
미입력(null): taxYn을 보내지 않으면 등록된 가맹점 정보 기준으로 과세구분을 판단하고 amt(총 거래금액)에서 자동 계산
└amtN(10)숫자, 최대 10byte*
공급가액
*과세: 과세금액, 면세: 면세금액, 복합과세: 과세+면세금액
└vatN(10)숫자, 최대 10byte*
부가세
*과세: 부가세, 면세: 0, 복합과세: 과세금액의 부가세
└svcAmtN(10)숫자, 최대 10byte
봉사료
└bizRegNoN(10)숫자, 최대 10byte
하위사업자번호
*하위사업자번호로 발급 시 taxYn을 하위사업자의 과세 타입으로 필수 입력해야 합니다.
└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: 전통시장내 도서공연비
*해당 추가공제 거래에만 입력
문화비 소득공제 제공 단일사업자는 값을 생략해도 문화비로 처리
전통시장/전통시장 내 문화비로 지정한 사업자번호가 국세청에 추가공제대상으로 등록되어 있지 않으면 TSN으로 결과를 받고 일반 소득공제로 등록되며, 추후 추가공제대상 등록 시 추가공제로 자동 적용됩니다
2025/07/01 이후 체육시설 사용료(수영장, 헬스 등)도 문화비(C)에 포함: 강습료 50%, 입장료와 대여료(수건, 운동복) 100% 공제

응답 파라미터

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

요청 예시

https://tcash.settlebank.co.kr/pgtrans/CashReceiptMultiAction.do?_method=insertReceiptInfo
&mid=mid_test
&assort=0
&transNo=AP20210316144106
&ordNm=
&trDt=20210316144106
&taxYn=N
&amt=9090
&vat=910
&svcAmt=0
&bizRegNo=1018163383
&purpose=0
&identityGb=4
&identity=0100001234
&deductionType=

응답 예시

성공

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

실패

{
  "trTime": "",
  "resultCd": "1010",
  "authNo": "",
  "resultMsg": "금액정보가 잘못되었습니다."
}

요청결과 코드

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

더 궁금한 내용이 있나요?

FAQ
💬

기술지원이 필요한가요?