목차

홈택스 접속 없이 토스페이먼츠에서 제공하는 현금영수증 API로 현금영수증을 편리하게 발급해보세요. 토스페이먼츠에서는 발급 요청된 현금영수증을 모아 국세청에 전달합니다. 토스페이먼츠로 결제하지 않은 건도 발급 및 취소 요청을 할 수 있습니다.

고객이 가상계좌나 계좌이체와 같이 현금성 결제수단으로 결제했다면, 고객이 현금영수증 발급을 신청하지 않았거나 발행을 원하지 않더라도 현금영수증 발급 의무에 따라 상점에서 현금영수증을 발행해야 합니다.

현금영수증 발급하기

샘플 프로젝트현금영수증 API 샘플 프로젝트입니다.

현금영수증을 발급할 때는 결제 정보 외에도 꼭 필요한 정보가 있습니다. 현금영수증 발급 용도와 현금영수증 발급에 필요한 소비자 인증수단입니다. 인증수단은 발급 용도에 따라 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호 중 하나로 현금영수증을 발급한 주체를 식별합니다.

현금영수증 발급 용도는 개인 소득 공제와 사업자 지출 증빙으로 나뉩니다. 소득 공제용 현금영수증을 발급받을 때는 소비자 인증수단으로 휴대폰 번호나 주민등록번호가 필요하고, 지출 증빙용 현금영수증을 발급받을 때는 사업자 등록번호를 입력해야 합니다.

현금영수증 발급 API를 요청할 때도 이 정보를 파라미터로 보내줘야 합니다. 요청 본문에 현금영수증 발급 용도를 type에 추가하고, 소비자 인증수단은 customerIdentityNumber에 추가해주세요.

아래 예시에서는 결제 고객의 소득 공제용 현금영수증을 발급하기 때문에 type 값으로 소득공제를 추가하고 customerIdentityNumber 값으로는 고객의 휴대폰 번호를 입력했습니다.

요청
curl --request POST \
  --url https://api.tosspayments.com/v1/cash-receipts \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"orderId":"1mQpgdYC_Ig9WV6f5WkqS","orderName":"토스 티셔츠 외 2건","amount":"10000","type":"소득공제","customerIdentityNumber":"01012345678"}'

만약 하나의 결제에 과세 상품과 면세 상품이 섞여있다면 taxFreeAmount 파라미터를 추가해서 면세 상품 금액을 보내주세요. 보낸 금액 만큼 현금영수증이 발급됩니다. 면세 금액을 처리하는 자세한 방법은 세금 처리하기에서 확인할 수 있습니다.

결제 고객의 정보가 없어도 상점에서 발급할 때 사용할 수 있는 국세청 지정 코드(010-000-1234)를 활용해 현금영수증을 발급할 수 있습니다.

API 응답은 아래와 같이 돌아옵니다.

응답
{
"receiptKey": "aZDBYqJLQ1GKNbdOvk5rkaLKaOYEn3n07xlzmj6R9e4oPpEX",
"orderId": "",
"orderName": "토스티셔츠 외 2건",
"type": "소득공제",
"issueNumber": "160594074",
"receiptUrl": "https://dashboard.tosspayments.com/receipts/cash-receipt/oid-220728/test_ka7r9?ref=PX",
"businessNumber": "1111111111",
"transactionType": "CONFIRM",
"amount": 10000,
"taxFreeAmount": 909,
"issueStatus": "IN_PROGRESS",
"failure": null,
"requestedAt": "2022-07-27T22:39:19+09:00",
"customerIdentityNumber": "01012345678"
}
JSON

응답 객체의 transactionType으로 현금영수증 발급(CONFIRM)과 현금영수증 발급 취소(CANCEL)를 구분할 수 있습니다. issueStatus는 요청의 상태를 나타냅니다. 응답의 최초 상태는 IN_PROGRESS입니다. 토스페이먼츠에 요청이 잘 전달되었음을 뜻합니다.

현금영수증 발급 요청 API로 발급한 정보이기 때문입니다. 결제할 때 요청한 것이 아니라 별도로 현금영수증 발급 요청 API로 발급한 현금영수증 정보는 결제 정보와 연결되지 않습니다. 따라서 결제 조회 API 결과로 돌아온 Payment.cashReceipts 필드는 null입니다. 현금영수증 조회 API로 조회해주세요.


현금영수증 발급 취소하기

현금영수증을 발급한 결제가 취소됐을 때 현급영수증 취소 API로 현금영수증 발급도 취소하세요. 현금영수증 발급 API의 응답으로 받았던 receiptKey를 저장하고 있다가 Path 파라미터로 추가하세요.

부분 취소는 amount 값에 취소된 금액을 입력해서 사용합니다. amount 값이 없으면 전액 취소됩니다.

취소가 정상적으로 되면 응답에 requestedAt 값이 포함되어 돌아옵니다.

응답
{
"receiptKey": "c_aZDBYqJLQ1GKNbdOvk5rkaLKaOYEn3n07xlzmj6R9e4oPpEX",
"orderId": "oid-220728",
"orderName": "",
"type": "소득공제",
"issueNumber": "160592932",
"receiptUrl": "https://dashboard.tosspayments.com/receipts/cash-receipt/oid-220728/test_ka7r9?ref=PX",
"businessNumber": "1111111111",
"transactionType": "CANCEL",
"amount": 5000,
"taxFreeAmount": 455,
"issueStatus": "IN_PROGRESS",
"failure": null,
"requestedAt": "2022-07-27T22:40:13+09:00",
"customerIdentityNumber": "01012345678"
}
JSON
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기