POPBill Developers
연동신청
  • 가이드 0
  • 레퍼런스 0
  • 오류코드 0
현금영수증
  • 전자세금계산서
  • 현금영수증
  • 전자명세서
  • 홈택스수집(세금)
  • 홈택스수집(현금)
  • 사업자등록상태조회
  • 기업정보조회
  • 계좌조회
  • 예금주조회
  • 카카오톡
  • 문자
  • 팩스
가이드

서비스에 대한 정확한 이해로
최적의 구현방식을 적용합니다.

SDK 레퍼런스

서비스에 대한 정확한 이해로
최적의 구현방식을 적용합니다.

팝빌의
SDK 다운로드
API 레퍼런스

서비스에 대한 정확한 이해로
최적의 구현방식을 적용합니다.

고객지원

API 연동 중 발생하는 문제는
팝빌에서 해결을 도와드립니다.

팝빌의
서비스 제안서 수많은 기업이
선택한 팝빌
API 레퍼런스
현금영수증
API 레퍼런스 현금영수증 발행

발행

1. RegistIssue - 승인 현금영수증 발행

POST https://popbill-test.linkhub.co.kr/Cashbill
POST https://popbill.linkhub.co.kr/Cashbill
  • 현금영수증 자진발급분은 소득공제 용도로만 발행 가능합니다. (자진발급 번호 : 010-000-1234)
  • 현금영수증 발행시 구매자 메일주소로 발행 안내 메일이 전송되니 유의하시기 바랍니다.
Request
요청 헤더
순번 변수명 필수 설명
Authorization Y 인증 토큰
[참고] 인증 및 헤더 설정
Content-Type Y 요청 본문 형식
application/json
Accept-Language N 응답 언어 설정
ko-KR: 기본값
en-US
Accept-Encoding N 응답 압축 방식
gzip
X-HTTP-Method-Override Y 요청 메서드 재정의
ISSUE
X-PB-UserID N 팝빌회원 아이디
요청 본문
순번 변수명 타입 길이 필수 설명
mgtKey string 24 Y 문서번호
문서 관리를 위해 파트너가 할당하는 식별번호
영문 대소문자, 숫자, 특수문자('-','_')만 이용 가능
tradeDT string 14 N 거래일시
전일부터 당일까지 입력 가능
형식 : yyyyMMddHHmmss
기본값 : 발행일시 사용
tradeType string 4 Y 문서형태
승인거래
tradeUsage string - Y 거래구분 (택 1)
소득공제용
지출증빙용
tradeOpt string 4 N 거래유형
일반 : 기본값
도서공연
대중교통
도서공연 : 도서, 공연, 박물관, 미술관, 수영장, 체력단련장, 신문구독료(종이신문), 영화관람료
taxationType string - Y 과세형태 (택 1)
과세
비과세
totalAmount string 9 Y 거래금액 (공급가액+부가세+봉사료)
양수만 입력
supplyCost string 9 Y 공급가액
양수만 입력
tax string 9 Y 부가세
양수 또는 0 입력
serviceFee string 9 Y 봉사료
양수 또는 0 입력
franchiseCorpNum string 10 Y 가맹점 사업자번호
팝빌회원 사업자번호 ('-' 제외)
franchiseTaxRegID string 4 N 가맹점 종사업장 식별번호
종사업장 식별번호는 4자리 숫자로만 구성
franchiseCorpName string 200 N 가맹점 상호
franchiseCEOName string 100 N 가맹점 대표자 성명
franchiseAddr string 400 N 가맹점 주소
franchiseTEL string 20 N 가맹점 전화번호
identityNum string 19 Y 식별번호
- {tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 입력
- {tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 입력
주민등록번호 13자리, 휴대폰번호 10~11자리, 카드번호 13~19자리, 사업자번호 10자리 입력 가능
customerName string 70 N 구매자(고객) 성명
itemName string 70 N 주문 상품명
orderNumber string 200 N 주문번호
email string 100 N 구매자(고객) 메일
hp string 20 N 구매자(고객) 휴대폰
smssendYN boolean - N 구매자 알림문자 전송 여부
true전송
false미전송 : 기본값
수신자 : 구매자 휴대폰번호 {hp}
문자 전송 포인트가 차감(단, 전송실패 건은 환불)
memo string 200 N 현금영수증 상태 이력을 관리하기 위한 메모
emailSubject string 300 N 현금영수증 발행 안내메일 제목
기본값 : 팝빌에서 설정한 안내메일 제목
요청 예시
curl --request POST \
  --url 'https://{domain}/Cashbill' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --header 'X-HTTP-Method-Override: ISSUE' \
  --data '{
    "mgtKey": "TEST0001",
    "tradeType": "승인거래",
    "tradeUsage": "지출증빙용",
    "taxationType": "과세",
    "totalAmount": "11000",
    "supplyCost": "10000",
    "tax": "1000",
    "serviceFee": "0",
    "franchiseCorpNum": "1234567890",
    "identityNum": "1234567890"
  }'
Response
응답 본문
순번 변수명 타입 길이 설명
code number - API 처리에 대한 응답코드
1성공
message string - API 처리에 대한 응답메시지
confirmNum string 24 국세청승인번호
현금영수증 발행 시점에 팝빌에서 자동으로 할당
tradeDate string 8 거래일자
현금영수증 발행 시점에 팝빌에서 자동으로 할당
형식 : yyyyMMdd
응답 예시
{
    "code": 1,
    "message": "발행 완료",
    "confirmNum": "TB0000032",
    "tradeDate": "20251023"
}

2. RevokeRegistIssue - 취소 현금영수증 발행

POST https://popbill-test.linkhub.co.kr/Cashbill
POST https://popbill.linkhub.co.kr/Cashbill
  • 당초 승인 현금영수증의 취소거래 발행 API 입니다.
  • 작성된 취소 현금영수증 데이터를 팝빌에 저장과 동시에 발행하여 "발행완료" 상태로 처리합니다. [참고] 팝빌 국세청 전송 정책
  • 부분 취소 현금영수증을 발행하는 경우 isPartCancel 값을 true 로 설정하여 주시기 바랍니다.
  • 당초 국세청승인번호와 거래일자는 [GetInfo – 상태확인]함수를 통해 확인 가능합니다.
유의사항
  • 당초 승인 현금영수증의 거래일시보다 과거의 거래일시를 입력할 수 없습니다.
  • 취소 현금영수증의 거래금액의 합은 당초 승인 현금영수증의 거래금액을 넘을 수 없습니다.
  • 취소 현금영수증 발행시 구매자 메일주소로 발행 안내 메일이 전송되니 유의하시기 바랍니다.
Request
요청 헤더
순번 변수명 필수 설명
Authorization Y 인증 토큰
[참고] 인증 및 헤더 설정
Content-Type Y 요청 본문 형식
application/json
Accept-Language N 응답 언어 설정
ko-KR: 기본값
en-US
Accept-Encoding N 응답 압축 방식
gzip
X-HTTP-Method-Override Y 요청 메서드 재정의
REVOKEISSUE
X-PB-UserID N 팝빌회원 아이디
요청 본문
순번 변수명 타입 길이 필수 설명
mgtKey string 24 Y 파트너가 할당한 문서번호
영문 대소문자, 숫자, 특수문자('-','_')만 이용 가능
orgConfirmNum string 9 Y 당초 국세청승인번호
[GetInfo - 상태 확인] API의 리턴값 confirmNum을 통해 내용 확인 가능
orgTradeDate string 8 Y 당초 거래일자
[GetInfo - 상태 확인] API의 리턴값 tradeDate를 통해 내용 확인 가능
smssendYN boolean - N 현금영수증 발행시 알림문자 전송 여부
true전송
false미전송 : 기본값
당초 승인 현금영수증의 구매자(고객)의 휴대폰번호 문자 전송
memo string 200 N 현금영수증 상태 이력을 관리하기 위한 메모
isPartCancel boolean - N 현금영수증 취소유형
true부분 취소
false전체 취소 : 기본값
cancelType number 1 N 현금영수증 취소사유
1거래취소 : 기본값
2오류발급취소
3기타
supplyCost string 9 조건부 부분 취소 공급가액
양수만 입력
{isPartCancel}=true 경우 필수
tax string 9 조건부 부분 취소 부가세
양수 또는 0 입력
{isPartCancel}=true 경우 필수
serviceFee string 9 조건부 부분 취소 봉사료
양수 또는 0 입력
{isPartCancel}=true 경우 필수
totalAmount string 9 조건부 부분 취소 거래금액
양수만 입력
거래금액 = 공급가액 + 부가세 + 봉사료
{isPartCancel}=true 경우 필수
emailSubject string 300 N 현금영수증 발행 안내메일 제목
기본값 : 팝빌에서 설정한 안내메일 제목
tradeDT string 300 N 거래일시
전일부터 당일까지 입력 가능
형식 : yyyyMMddHHmmss
기본값 : 발행일시 사용
요청 예시
curl --request POST \
  --url 'https://{domain}/Cashbill' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --header 'X-HTTP-Method-Override: REVOKEISSUE' \
  --data '{
    "mgtKey": "TEST0002",
    "orgConfirmNum": "TB0000032",
    "orgTradeDate": "20251023"
  }'
Response
응답 본문
순번 변수명 타입 길이 설명
code number - API 처리에 대한 응답코드
1성공
message string - API 처리에 대한 응답메시지
confirmNum string 24 국세청승인번호
현금영수증 발행 시점에 팝빌에서 자동으로 할당
tradeDate string 8 거래일자
현금영수증 발행 시점에 팝빌에서 자동으로 할당
형식 : yyyyMMdd
응답 예시 
{
    "code": 1,
    "message": "발행 완료",
    "confirmNum": "TB0000032",
    "tradeDate": "20251023"
}

3. BulkSubmit - 초대량 발행 접수

POST https://popbill-test.linkhub.co.kr/Cashbill
POST https://popbill.linkhub.co.kr/Cashbill
  • 최대 100건의 현금영수증 발행을 한번의 요청으로 접수합니다.
  • 현금영수증 자진발급분은 소득공제 용도로만 발행 가능합니다. (자진발급 번호 : 010-000-1234)
  • 현금영수증 발행시 구매자 메일주소로 발행 안내 메일이 전송되니 유의하시기 바랍니다.
Request
요청 헤더
순번 변수명 필수 설명
Authorization Y 인증 토큰
[참고] 인증 및 헤더 설정
Content-Type Y 요청 본문 형식
application/json
Accept-Language N 응답 언어 설정
ko-KR: 기본값
en-US
Accept-Encoding N 응답 압축 방식
gzip
X-PB-Submit-ID Y 제출아이디
영문, 숫자, '-' 조합으로 최대 36자 길이로 구성
X-HTTP-Method-Override Y 요청 메서드 재정의
BULKISSUE
X-PB-Message-Digest Y Message Digest
요청 본문의 무결성을 검증하는데 사용
[참고] X-PBMessage-Digest
X-PB-UserID N 팝빌회원 아이디
요청 본문
순번 변수명 타입 길이 필수 설명
cashbills array - Y 현금영수증 목록
최대 : 100건
순번 변수명 타입 길이 필수 설명
mgtKey string 24 Y 문서번호
문서 관리를 위해 파트너가 할당하는 식별번호
영문 대소문자, 숫자, 특수문자('-','_')만 이용 가능
tradeDT string 14 N 거래일시
전일부터 당일까지 입력 가능
형식 : yyyyMMddHHmmss
기본값 : 발행일시 사용
tradeType string 4 Y 문서형태
승인거래
tradeUsage string - Y 거래구분 (택 1)
소득공제용
지출증빙용
tradeOpt string 4 N 거래유형
일반 : 기본값
도서공연
대중교통
도서공연 : 도서, 공연, 박물관, 미술관, 수영장, 체력단련장, 신문구독료(종이신문), 영화관람료
taxationType string - Y 과세형태 (택 1)
과세
비과세
totalAmount string 9 Y 거래금액 (공급가액+부가세+봉사료)
양수만 입력
supplyCost string 9 Y 공급가액
양수만 입력
tax string 9 Y 부가세
양수 또는 0 입력
serviceFee string 9 Y 봉사료
양수 또는 0 입력
franchiseCorpNum string 10 Y 가맹점 사업자번호
팝빌회원 사업자번호 ('-' 제외)
franchiseTaxRegID string 4 N 가맹점 종사업장 식별번호
종사업장 식별번호는 4자리 숫자로만 구성
franchiseCorpName string 200 N 가맹점 상호
franchiseCEOName string 100 N 가맹점 대표자 성명
franchiseAddr string 400 N 가맹점 주소
franchiseTEL string 20 N 가맹점 전화번호
identityNum string 19 Y 식별번호
- {tradeUsage} 값이 "소득공제용" 경우 주민등록/휴대폰/카드번호/자진발급용 번호(010-000-1234) 입력
- {tradeUsage} 값이 "지출증빙용" 경우 사업자번호/휴대폰/카드번호 입력
주민등록번호 13자리, 휴대폰번호 10~11자리, 카드번호 13~19자리, 사업자번호 10자리 입력 가능
customerName string 70 N 구매자(고객) 성명
itemName string 70 N 주문 상품명
orderNumber string 200 N 주문번호
email string 100 N 구매자(고객) 메일
hp string 20 N 구매자(고객) 휴대폰
smssendYN boolean - N 구매자 알림문자 전송 여부
true전송
false미전송 : 기본값
수신자 : 구매자 휴대폰번호 {hp}
문자 전송 포인트가 차감(단, 전송실패 건은 환불)
memo string 200 N 현금영수증 상태 이력을 관리하기 위한 메모
emailSubject string 300 N 현금영수증 발행 안내메일 제목
기본값 : 팝빌에서 설정한 안내메일 제목
요청 예시
curl --request POST \
  --url 'https://{domain}/Cashbill' \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --header 'X-HTTP-Method-Override: BULKISSUE' \
  --header 'X-PB-Submit-ID: {submitID}' \
  --header 'X-PB-Message-Digest: {messageDigest}' \
  --data '{
    "cashbills": [
        {
            "mgtKey": "TEST0004",
            "tradeType": "승인거래",
            "tradeUsage": "지출증빙용",
            "taxationType": "과세",
            "totalAmount": "11000",
            "supplyCost": "10000",
            "tax": "1000",
            "serviceFee": "0",
            "franchiseCorpNum": "1234567890",
            "identityNum": "1234567890"
        }
    ]
  }'
Response
응답 본문
순번 변수명 타입 길이 설명
code number - API 처리에 대한 응답코드
1성공
message string - API 처리에 대한 응답메시지
receiptID string 36 접수아이디
응답 예시 
{
  "code": 1,
  "message": "접수 완료",
  "receiptID": "0251024-f842ed73b6004518bf5bc73c1d9f"
}

4. GetBulkResult - 초대량 접수결과 확인

GET https://popbill-test.linkhub.co.kr/Cashbill/Bulk/{submitID}/State
GET https://popbill.linkhub.co.kr/Cashbill/Bulk/{submitID}/State
  • 접수시 기재한 SubmitID를 사용하여 현금영수증 접수결과를 확인합니다.
  • 개별 현금영수증 처리상태는 접수상태(txState)가 완료(2) 시 반환됩니다.
Request
요청 헤더
순번 변수명 필수 설명
Authorization Y 인증 토큰
[참고] 인증 및 헤더 설정
Accept-Language N 응답 언어 설정
ko-KR: 기본값
en-US
Accept-Encoding N 응답 압축 방식
gzip
X-PB-UserID N 팝빌회원 아이디
Path 파라미터
순번 변수명 타입 길이 필수 설명
submitID string 36 Y 파트너가 할당한 제출아이디
요청 예시
curl --request GET \
  --url 'https://{domain}/Cashbill/Bulk/{submitID}/State' \
  --header 'Authorization: Bearer {token}'
Response
응답 본문
순번 변수명 타입 길이 설명
code number - API 처리에 대한 응답코드
1성공
message string - API 처리에 대한 응답메시지
submitID string 36 접수 시점에 고객사에서 할당한 제출아이디
submitCount number - 현금영수증 접수 건수
successCount number - 현금영수증 발행 성공 건수
failCount number - 현금영수증 발행 실패 건수
txState number 1 접수상태
0접수
1처리중
2처리완료
txResultCode number - 접수 결과코드
- 성공 : 1
- 실패 : 음의 정수 8자리 숫자값 [참고] 오류코드
txStartDT string 14 발행처리 시작일시
형식 : yyyyMMddHHmmss
txEndDT string 14 발행처리 완료일시
형식 : yyyyMMddHHmmss
receiptID string 36 접수아이디
접수 시점에 팝빌에서 자동으로 할당
issueResult array - 발행결과
순번 변수명 타입 길이 설명
code number - API 처리에 대한 응답코드
1성공
message string - API 처리에 대한 응답메시지
mgtKey string 24 문서번호
confirmNum string 9 국세청승인번호
현금영수증 발행 시점에 팝빌에서 자동으로 할당
tradeDate string 8 거래일자
현금영수증 발행 시점에 팝빌에서 자동으로 할당
{tradeDT}의 yyyyMMdd
issueDT string 14 발행일시
형식 : yyyyMMddHHmmss
receiptDT string 14 접수일시
형식 : yyyyMMddHHmmss
응답 예시
{
    "code": 1,
    "message": "확인 완료",
    "receiptID": "0251024-bf8026eae6d64e44854593e5fa82",
    "submitID": "20251024-JAVA3",
    "submitCount": 5,
    "successCount": 5,
    "failCount": 0,
    "txState": 2,
    "txStartDT": "20251024140659",
    "txEndDT": "20251024140700",
    "txResultCode": 1,
    "issueResult": [
        {
            "mgtKey": "20251024-0",
            "code": 1,
            "confirmNum": "TB0000048",
            "tradeDate": "20251024",
            "issueDT": "20251024140659"
        }
    ],
    "receiptDT": "20251024140659"
}

5. Delete - 삭제

POST https://popbill-test.linkhub.co.kr/Cashbill/{MgtKey}
POST https://popbill.linkhub.co.kr/Cashbill/{MgtKey}
  • 삭제 가능한 상태의 현금영수증을 삭제합니다.

    ※ 삭제 가능한 상태: "전송실패"

  • 삭제 처리된 현금영수증의 문서번호는 재사용이 가능합니다.
Request
요청 헤더
순번 변수명 필수 설명
Authorization Y 인증 토큰
[참고] 인증 및 헤더 설정
Accept-Language N 응답 언어 설정
ko-KR: 기본값
en-US
Accept-Encoding N 응답 압축 방식
gzip
X-HTTP-Method-Override Y 요청 메서드 재정의
DELETE
X-PB-UserID N 팝빌회원 아이디
Path 파라미터
순번 변수명 타입 길이 필수 설명
MgtKey string 24 Y 파트너가 할당한 문서번호
요청 예시
curl --request POST \
  --url 'https://{domain}/Cashbill/{MgtKey}' \
  --header 'Authorization: Bearer {token}' \
  --header 'X-HTTP-Method-Override: DELETE'
Response
응답 본문
순번 변수명 타입 길이 설명
code number - API 처리에 대한 응답코드
1성공
message string - API 처리에 대한 응답메시지
응답 예시 
{
    "code": 1,
    "message": "삭제 완료"
}